
Lotus Agenda 

Working with Definition Files 


Release 2.0 












Lotus Agenda 

Working with Definition Files 


Release 2.0 


Neither the documentation nor the software may be copied, photocopied, reproduced, translated, or 
reduced to any electronic medium or machine-readable format, except in the manner described in the 
documentation. 

© Copyright 1988,1989,1990 Lotus Development Corporation 

55 Cambridge Parkway 
Cambridge, MA 02142 

All rights reserved. First edition printed 1988. Second edition printed 1989. Third edition printed 1990. 
Printed in the United States. 

Lotus, Lotus Agenda, Agenda, Lotus Express, Lotus Metro, 1-2-3, and One Source CD/Corporate are regis¬ 
tered trademarks of Lotus Development Corporation. MCI Mail is a registered trademark of MCI Commu¬ 
nications Corporation. PROFS is a registered trademark of International Business Machines, Inc. The 
Industry Participants List and Financials are provided by Disclosure, Inc. and the Lotus One Source 
CD/Corporate product is provided by Data Source: Disclosure, Inc. 



Contents 


Introduction ix 


How this Book Is Organized. ix 

Before You Begin. xi 

Typographic Conventions . xi 


Chapter 1 Getting Started with Definition Files 1-1 


In this Chapter. 1-2 

About Definition Files . 1-2 

When to Use a Definition File . 1-4 

Benefits of Using Definition Files. 1-4 

When Other Approaches Are Appropriate. 1-4 

Creating a Definition File. 1-5 

Analyzing the Text File. 1-5 

Writing the Definition File Patterns and Commands . 1-7 


Chapter 2 Creating a Definition File 2-1 


In this Chapter... 2-1 

Creating a Definition File... 2-1 

Analyzing the Text File . 2-2 

Writing the Definition File Patterns and Commands . 2-3 

What a Definition File Contains . 2-3 

Guidelines for Writing Statements. 2-3 

Including Comments in a Definition File. 2-5 

Using ©start and @end . 2-5 

























iv Contents 


How TXT2STF Uses the Definition Rle.2-7 

How TXT2STF Processes Each Text Line. 2-8 

How TXT2STF Builds Items, Categories, and Notes. 2-10 


Chapter 3 Using Definition Files 3-1 


About this Chapter. 3-1 

Converting an Electronic Mail Message . 3-2 

Sample Text File. 3-2 

Sample Definition File . 3-4 

After the Structured File Is Imported... 3-10 

Converting a Table of Information. 3-10 

Sample Text File. 3-11 

Sample Definition File . 3-13 

After the Structured File Is Imported. 3-16 


Chapter 4 Patterns _4-1 


In this Chapter . 4-1 

About Patterns . 4-1 

Special Patterns. 4-2 

START. 4-3 

END. 4-3 

Using START and END. 4-3 

Match-Control Characters. 4-4 

Asterisk (*) . 4-5 

Backslash (\). 4-6 

Brackets ([ ]). 4-6 

Caret ( A ) . 4-8 

Colon a (:a). 4-9 

Colon d (:d). 4-10 

Colon n (:n). 4-10 

Colon Space (: ) . 4-10 

Dollar Sign ($) . 4-11 

Parentheses () . 4-11 

Period (.). 4-12 

Plus (+) . 4-12 

Tilde (~). 4-13 

Vertical Bar (!). 4-14 






































Contents v 


How TXT2STF Matches Patterns . 4-14 

When TXT2STF Matches Patterns. 4-14 

How TXT2STF Compares Patterns with Strings. 4-16 

How TXT2STF Searches for Character Classes. 4-18 


Chapter 5 Definition File Commands 5-1 


In this Chapter ... 5-1 

About Commands . 5-1 

Types of Commands . 5-3 

Command Syntax . 5-6 

About Arguments. 5-8 

About Variables. 5-11 

Specifying Variables in Commands. 5-12 

Predefined Variables. 5-12 

©append . 5-13 

@append_item. 5-14 

@append_note . 5-17 

©category. 5-19 

@category_note. 5-22 

@category_note_file . 5-24 

@custom_category . 5-25 

©date . 5-28 

@date_format. 5-29 

©end. 5-32 

©equate. 5-33 

©grab. 5-34 

©item. 5-37 

@item2. 5-40 

@make_extemaLnote . 5-43 

©note. 5-45 

@note_file. 5-48 

©numeric. 5-49 

©replace. 5-51 

©reset . 5-52 

©set. 5-55 

©skip. 5-55 

@skip_lines. 5-57 

©start. 5-59 

©strip . 5-60 

©table. 5-62 

©trim . 5-64 

©unindexed . 5-67 











































vi Contents 


Chapter § Converting anti importing Text W 


In this Chapter . 6-1 

Running TXT2STF . 6-1 

The TXT2STF Command . 6-2 

File Conversion Options. 6-2 

How TXT2STF Converts Text Files. 6-3 

Specifying a Definition File to Use with a Text File . 6-3 

Specifying a Different Name for the Structured File. 6-4 

Specifying an Alternate Separator Character for a Text File ... 6-5 

Converting More Than One Text File. 6-6 

Importing the Structured File . 6-6 


Chapter 7 Debugging a Definition File 7-1 


In this Chapter . 7-1 

Procedures for Debugging a Definition File . 7-2 

Testing a Definition File. 7-2 

Naming a Structured File. 7-3 

Including Debugging Options. 7-3 

Redirecting Error Messages to a File. 7-4 

Examining the Converted Information. 7-4 

Examining the Structured File. 7-4 

Importing the Converted Information . 7-5 

Typical Problems and Solutions . 7-5 

Testing for Pattern Matching. 7-6 

Testing How Information Is Converted. 7-7 

Tips and Techniques . 7-8 

Writing Patterns. 7-8 

Ordering Statements ..... 7-9 

Skipping Over Text ... 7-10 

Handling More Than One Text Layout. 7-12 

Creating More Than One Item. 7-13 
































Contents vii 


Appendix A What’s New in TXT2STF for Agenda 2.0 A-1 


In this Appendix. A-1 

Running TXT2STF . A-1 

Definition Files. A-2 

Patterns . A-3 

Definition File Commands. A-4 

Structured File Tags. A-5 


Appendix B Structured Files B-1 


In this Appendix. B-1 

About Structured Files . B-1 

What a Structured File Contains. B-2 

Creating Your Own Structured File. B-3 

Structured File Tags. B-3 

Structured File Header Tag.B-5 

Comment Tag. B-6 

Date Format Tags. B-6 

Note Tags. B-8 

Category Tags . B-10 

Item Tags. B-14 

What Structured Files Look Like. B-16 

A Simple Electronic Mail Example . B-16 

Sample Structured Files. B-18 


Appendix C Quick Reference C-1 


Patterns . C-1 

Match-Control Characters. C-1 

Special Patterns. C-2 

Definition File Commands. C-3 

Command Syntax. C-3 

Predefined Variables. C-5 
































viii Contents 


Appendix D Error Messages D-1 


In this Appendix. D-1 

About Error Messages . D-1 

Error Messages and Descriptions. D-2 


Index 









Introduction 


Working with Definition Files provides information about writing and 
debugging definition files to use with the Lotus Agenda® TXT2STF 
utility. 

TXT2STF is a versatile utility that prepares text to be imported into 
Agenda. To guide TXT2STF, you can create definition files that pro¬ 
vide custom instructions for converting the contents of text files into 
Agenda items, categories, and notes. 


How this Book Is Organized 


Working with Definition Files is organized into seven chapters and four 

appendixes that provide the following information: 

• Chapter 1, "Getting Started with Definition Files," describes 
what a definition file is, when you need to write definition files, 
and provides an example of how you might write a definition file 
to convert a text file. 

Read this chapter to get an overview of what definition files are 
and when to use them. 

• Chapter 2, "Creating a Definition File," describes how to create a 
definition file and what a definition file contains. This chapter 
also describes how TXT2STF uses the definition file to process a 
text file based on the definition file you write. 

Read this chapter for a basic understanding of how to write a 
definition file. 

• Chapter 3, "Using Definition Files," provides examples of what 
you can do with a definition file. This chapter presents examples 
of text files along with definition files that convert the text files, 
and shows how the converted information looks after you import 
it into Agenda. 


ix 




Read this chapter to see some examples of how actual definition 
files convert text for importing into Agenda. 

Chapter 4, "Patterns;' provides specific information about writing 
patterns in definition files, including a list of match-control char¬ 
acters you can use in patterns. 

Read this chapter to learn about patterns in definition files, or as a 
reference when creating definition files. 

Chapter 5, "Definition File Commands," provides specific infor¬ 
mation about using commands in definition files, including a list 
of all the commands with examples. 

Read this chapter to learn about definition file commands, or as a 
reference when creating definition files. 

Chapter 6, "Converting and Importing Text/’ describes how to 
run TXT2STF to convert your text file into a structured file and 
how to import the structured file into Agenda. 

Read this chapter when you're ready to rim TXT2STF and use 
your definition file to convert text for importing into Agenda. 

Chapter 7, "Debugging a Definition File," explains how to debug 
your definition file and gives tips on how to write better definition 
files. 

Read this chapter when you've created a definition file and you 
want to test how accurately it converts your text. 

Appendix A, "What's New in TXT2STF for Agenda 2.0" lists new 
and changed TXT2STF features that support Agenda Release 2.0 
features, enhance TXT2STF performance, and give you greater 
control over how TXT2STF converts text files into structured files. 

Read this chapter if you've used a previous release of TXT2STF, 
and you want a quick overview of what's changed. 

Appendix B, "Structured Files," provides details about structured 
files, which are the intermediate ASCII files created by TXT2STF 
to hold the converted text. This chapter describes the special tags 
that TXT2STF embeds in the structured file that provide Agenda 
with details about how to import the converted text. 

Read this chapter when you are debugging a definition file, or 
when you are creating your own structured files using a tool other 
than TXT2STF. 
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• Appendix C," Quick Reference/' is a quick reference to definition 
file patterns, match-control characters, commands, and predefined 
variables for commands. 

Read this appendix when you need a quick review of definition 
file pattern and command syntax. 

* Appendix D, "Error Messages," lists the error messages you may 
see when running TXT2STF with definition files and describes 
possible reasons for them and possible solutions. 

Consult this chapter if you receive error messages when you run 
TXT2STF with a definition file. 


Before You Begin 


You should understand how to use Agenda before you begin to write 
definition files. In particular, you should be familiar with the way 
Agenda imports information. For more information, see Chapters 23 
and 24 in the User's Guide. 


Typographic Conventions 


Working with Definition Files uses the following typographical conven¬ 
tions: 

Information that you type is in a different typeface. 

Example 

Call Meg tomorrow 


Agenda commands, settings, and choices are in boldface type. 
Example 

To import the contents of a text file, use the File Transfer Import 
command. 





Chapter 1 

Getting Started with Definition Files 


Agenda lets you import information from other sources into your 
Agenda file. For example, you can import text from a memo created 
by using a word processor. In some instances, such as when you 
import the contents of a text file into an item note, this involves a sim¬ 
ple combination of two or three keystrokes. 

In other cases, you might want to import information that is for¬ 
matted in a more complicated manner. For example, you might want 
Agenda to create new items, modify the existing category hierarchy, 
or even add to the category hierarchy when it imports text. So that 
Agenda can import information in the way that you want, you must 
first structure the text into a format that Agenda understands. 

Agenda provides two utilities for this purpose: 

• TXT2STF (Text to Structured File) formats generic text files and is 
discussed in this book. 

• LM2STF (List Manager to Structured File) formats files created by 
the Lotus Metro List Manager. For information on LM2STF, see 
Chapter 23 of the User's Guide. 

This book focuses on the use of definition files with the TXT2STF 
utility. Definition files guide the activities of the TXT2STF utility and 
tell TXT2STF how to process text files to be imported into Agenda. 

Note The information TXT2STF converts must be in an ASCII text 
file. Most software products, such as word processors, add 
hidden formatting codes to files. However, most products 
also let you create ASCII text files (which do not include hid¬ 
den formatting codes). For example, a Lotus 1-2-3® PRN file, 
created by printing to a file, is such a text file. 
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In this Chapter 


This chapter describes how to use definition files and provides a sim¬ 
ple example that illustrates basic concepts about definition files and 
how they work. 

This chapter, along with Chapter 2, provide background information 
that describe why and how you create definition files. Even if you 
are familiar with programming concepts and/or with Agenda, it is 
still important to read through both of these chapters before trying to 
create your own definition files. The concepts and examples in these 
two chapters will help you understand the unique features of defini¬ 
tion files and the way they interact with TXT2STF. 

For more information on what to put in a definition file, see 
Chapter 2. For more information about importing text files, see 
Chapter 23 in the User's Guide. 


About Definition Files 


TXT2STF is a versatile utility, and can process many different types of 
text. For example, TXT2STF can process text files containing informa¬ 
tion as varied as electronic mail, online news stories, magazine article 
abstracts, tabular output from worksheets, and records from a 
traditional database. 

TXT2STF processes the contents of text files, structuring the text so 
that Agenda can import specific portions of text as items, categories, 
and notes. By default, when TXT2STF formats a text file, it makes the 
first 350 characters in each new paragraph into an item, and makes 
the remaining paragraph text into a note for the item. 

To have more control over how Agenda formats imported informa¬ 
tion, you can create a definition file. A definition file describes pat¬ 
terns of text in the text file, and contains commands that tell TXT2STF 
how to convert the text identified by these patterns into items, 
categories, and notes. The definition file is tailored to follow the 
layout and content of the text file. 

The definition file is created before you run TXT2STF, and is used 
when you request the definition file in the TXT2STF command. 
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TXT2STF converts the text file according to the instructions in the 
definition file, and puts the results in a structured file (text in the file 
is structured in a way that Agenda can interpret). 

Figure 1-1 shows the flow of information from text file to structured 
file when you run TXT2STF with a definition file. 


Text file 


* 



(Optional) 


| TXT2STF 

1 utility 

4 - 

Definition file 




* 


Structured file 


Figure 1-1 Converting a text file to a structured file with an 
optional definition file 


You import the structured file into Agenda by using the Agenda 
File Transfer Import command. (See Chapter 23 in the User's Guide.) 
This command tells Agenda how to incorporate information from the 
structured file into your Agenda file. 
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When to Use a Definition File 


You can use a definition file any time you run TXT2STF to convert a 
text file for importing. Using a definition file is particularly helpful if 

• You have many text files with the same format that you want to 
import into Agenda, such as a series of files that contain legal 
information, all of which are formatted in a similar way. 

• You frequently import specific types of files, such as electronic 
mail files. 

In these cases, you can use the definition file to automate the conver¬ 
sion of specific types of text into items, categories, and notes. For 
example, the definition file can tell TXT2STF to start a new item when 
it finds a subject line in an electronic mail file, to make the sender and 
recipient names into categories, and to put the body of the electronic 
mail into a note for the item. If you use TXT2STF without a definition 
file and then import the text, you would need to do much of this 
formatting yourself in Agenda after you import the text. 


Benefits of 
Using Definition 
Files 


There are various benefits to using a definition file to format text 
before you import it into Agenda. When you use a definition file 


• You control exactly what text Agenda will interpret as items, cate¬ 
gories, and notes. 

• You can set dates and make other category assignments for items. 

• You can predefine the category hierarchy. 


When Other You don't have to use a definition file to import a text file. If you only 

Approaches Are need to import one or two files of a given format, you might not want 

Appropriate to take the time to write a definition file. In that case, you can 

• Run TXT2STF without a definition file and import the structured 
file. (See Chapter 23 of the User's Guide.) 

• Import the text file into an Agenda note and then, within the note, 
make selected note text into items and categories. (See Chapter 12 
of the User's Guide.) 
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Or, you might want to use a different tool to create the structured file. 
For example, if the text file is patterned in a complex manner, you 
might prefer to write a program in a programming language such as 
BASIC or PASCAL to convert the text file into a structured file. For 
more information about what the structured file should contain, see 
Appendix B. 




Creating a Definition File 


This section describes one way to create a definition file. It presents a 
sample text file and describes the procedures you follow to create a 
corresponding definition file. 

As you read this section, remember that there are usually several 
ways to convert the same text file. For example, you might want to 
collect different item text from the text file. Your Agenda file might 
organize information in a different manner than is outlined in this 
example, so you might need to create different categories. 

Also remember that the definition file described in this section is tai¬ 
lored to the sample text file. You can use strategies described in this 
section in definition files that you create, but you need to adapt them 
to fit your own text files, whose contents and format will differ from 
the text file shown in this example. 

To create a definition file that can convert a text file into items, cate¬ 
gories, and notes, you must 

• Analyze the text file to determine what text to convert 

• Write the definition file, adding information that tells TXT2STF 
how to convert the text 

Analyzing the The first step in creating a definition file is to analyze the text file to 

Text File determine which text to convert into items, categories, and notes. 

Figure 1-2 shows a sample text file that you might want to bring into 
an Agenda file. This sample text file contains a memo sent to an 
Agenda user by electronic mail. 
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SEND_VIA NODE42 

Date: November 23 

To: Jill 

From: Linda 

Re: Lunch 

Can't make lunch appointment today, can we reschedule for next week? 


Figure 1-2 A sample text file 


In the current example, you could convert 

• The mail date into a When date 

• The recipient and sender names into categories 

• The mail subject line (labeled Re:) into an item 

• The body of the memo into a note for the item 

After you determine which text to convert, you must tell TXT2STF 
how to identify the text. To do this, look through the text file and 
locate text strings that label the text to convert. In the current exam¬ 
ple, this is easy to do, since electronic mail files contain standard 
labels that describe the information in the file. Date: labels the date. 
To: labels the memo recipient, and so forth. 

As shown in Figure 1-3, you want TXT2STF to convert text following 
Date: into a When date, the names following To: and From: into cate¬ 
gories, the text following Re: into the item, and the remaining text 
into a note for that item. By identifying these text strings, you give 
TXT2STF patterns it can use to locate the text you want to convert. 
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Text file _ 

SEND_VIA NODE_42 
Date: November 19 
To: Jill 
From: Linda 
Subject: Lunch 

Can’t make lunch 
appointment today, can we 
reschedule for next week? 


TXT2STF 

utility 


Definition file 


= When date 
= Category 
= Category 
= Item 


= Note 


Date: I I 

To: I 1 

From: l l 

Re: I Z) 


Structured file 
November 19 = When date 
Jill = Category 
From = Category 
Lunch = Item 
Can’t make lunch \ 
appointment today, ( 
can we reschedule r 
for next week? ) 


Figure 1-3 Using a definition file to convert text to import 
into Agenda 


Writing the 
Definition File 
Patterns and 
Commands 


Now that you know what information you want converted and have 
text strings that identify the text you have enough information to 
write a definition file. For each text line you want to convert you 
must 

• Add a pattern that describes to TXT2STF the text strings you want 
TXT2STF to find 

• Provide the commands required to convert the text located by the 
pattern into an item, category, note, or some combination 
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The combination of a pattern and its commands is called a statement. 
A definition file statement must start with a pattern and can include 
any number of commands. 

Adding patterns 

Patterns describe the text strings you want TXT2STF to find in the 
text file. By locating any of these lines in the text file, TXT2STF 
locates a line with information to be converted. To convert the elec¬ 
tronic mail message in Figure 1-2, you can add the following patterns: 

" A Date\:" 

" A To\: M 

,,A From\:" 

,<A Re\:" 

In the above patterns, the caret ( A ) tells TXT2STF that the text string 
begins a new line. The combination of backslash (\) and colon (:) in 
the above patterns tell TXT2STF that each colon (:) is a regular text 
character (otherwise, the colon (:) starts a special pattern condition). 
You include the carat ( A ), backslash (\), and other characters in pat¬ 
terns to provide additional information about the text string. For 
more information about patterns, see Chapter 4. 

When TXT2STF matches a text line with a pattern in the definition 
file, TXT2STF executes all commands related to the pattern. So far, 
you have created the patterns that TXT2STF can use to locate text to 
be converted. Now you can add commands to each pattern to tell 
TXT2STF how to convert the text that matches the pattern. 

Converting the When date 

Since "Date:" is the first text pattern in the sample text file, you can 
start the process of determining how to convert text with this text 
line. 

When TXT2STF finds "Date:" at the start of a line in an electronic mail 
file, you want TXT2STF to 

• Begin gathering information for a new item, consisting of text for 
the item itself as well as assignments for the item 

• Skip over the word Date and the colon (:) that follows it so that the 
string Date: does not occur in the When date 

• Convert the date into a When date 
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You set aside some computer memory for TXT2STF to use while con¬ 
structing your item and its note and categories by using the ©start 
command. To skip over text on a line, use ©skip. To make text into a 
When date, use ©date. Therefore, to convert text into a When date, 
you add the following pattern and commands: 


Pattern 

Commands 


,,A Date\:" 

©start 



©skip 



©date 



Note To simplify the current discussion, this chapter shows defini¬ 
tion file commands without their accompanying arguments. 
To see the complete commands with arguments, refer to 
Figure 1-4. 

Converting the To and From categories 

You can continue by creating the To and From categories, since To 
and From are the next strings of interest in the text file. 

In this example. To: labels the electronic mail recipient name and 
From: labels the sender name. You can have the definition file orga¬ 
nize sender names as children of the From category and recipient 
names as children of the To category. To do this, the definition file 
needs to keep track of both the parent category (To or From) and the 
child category (the name of the recipient or sender). 

When TXT2STF finds the string To: or From: at the start of a line in an 
electronic mail file, you want TXT2STF to 

• Convert the word To or From that starts the text line into a parent 
category 

• Convert the recipient or sender name into a child category of To 
or From 

You need to use two different portions of text from the same line: the 
parent category and the child category. One way to do this is to copy 
the parent and child categories into variables. Then, you can include 
these variables in the @custom_category command that assigns the 
child to the parent category. (For information about variables, see 
Chapters). For example: 
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Pattern Command 


A To\ : " @t rim (copies the parent category to a variable) 
@trim (copies the child category to a variable) 
@custom_category 


Since the same processing is required for both the To and From cate¬ 
gories, you can use a single statement to convert both types of text 
lines. To do this, you need to use a pattern that is generic enough to 
match both "From:” and "To:". 

You can use the pattern for this purpose. The carat ( A ) is the 

start-of-line character that tells TXT2STF that the string begins a new 
line in the text file. The combination of period (.) and asterisk (*) 
specifies that the string contains one or more characters. The combi¬ 
nation of backslash (\) and colon (:) specifies that the string ends in a 
colon (:). The pattern " A .*\:" therefore matches any string that starts 
at the beginning of a text line and ends in a colon (:). The following 
single statement handles all To and From lines in the electronic mail 
message: 


Pattern Commands 


" A . * \: " @ t r im (copies the parent category to a variable) 

@ t rim (copies the child category to a variable) 
@custom_category 


Converting the item and note 

When TXT2STF finds the string "Re:" at the start of a text line, you 
want TXT2STF to save the rest of the line as item text. 

The Agenda view into which you import electronic mail organizes 
electronic mail items as children under the parent category. Mes¬ 
sages. So, when TXT2STF finds the string Re: you want TXT2STF to 

• Specify that the new item will be assigned to a category called 
Messages 

• Skip the word Re and the colon (:) that follows it so the string Re: 
does not occur in the item text 

• Convert the remaining text in the line into an item 

• Create a note, starting on the next line and continuing to the end 
of the file 
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You specify that the new item will be assigned to a category by using 
@custom_category. To skip over text on a line, use ©skip. To make 
text into an item, use @item2 or ©item. To make a note for an item, 
use ©note. 

After TXT2STF creates the note, the item is complete. To tell 
TXT2STF to stop converting text for the item, use an ©end command. 
When TXT2STF executes ©end, it copies the item, categories, and 
note TXT2STF created to a structured file that is ready to be imported 
to Agenda. 

The statement that creates item and note text is as follows: 


Pattern 

Commands 

" A Re\:" 

©custom category 


©skip 


@item2 


©note 


©end 


Ordering the statements 

Because of the way TXT2STF converts a text file, the order of state¬ 
ments in a definition file can be very important. 

To convert a text file, TXT2STF steps through the text file, line by line. 
For each text line, TXT2STF compares the line with all of the state¬ 
ments in the definition file, starting at the first statement and working 
down to the end of the definition file. When a pattern in a statement 
matches text in the text line, TXT2STF executes the commands asso¬ 
ciated with the pattern. Then, TXT2STF continues to the next uncon¬ 
verted line in the text file and compares that line with statements, 
again starting at the top of the definition file. 

When you order statements in a definition file, you must be sure that 
the first pattern in the definition file that matches the text line is the 
desired pattern. When TXT2STF finds a statement that matches the 
current text line, it executes the commands in that statement. Then, 
TXT2STF moves on to the next line in the text file. No other state¬ 
ments are executed for the text line. 

In general, any statement with a pattern that precisely matches a spe¬ 
cific text line, and no other, should be placed early in the definition 
file. Put statements whose patterns are likely to match more than one 
text line toward the end of the definition file. If you follow this order- 
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ing scheme, TXT2STF compares text lines to statements with specific 
patterns before those with generic patterns. Text lines for which 
specific patterns exist match their patterns earlier in the conversion 
process, which expedites the conversion of text to structured informa¬ 
tion, and prevents them from incorrectly matching the more generic 
patterns. 

So far, this section has developed statements that 

• Convert the When date 

• Convert the To and From categories 

• Convert the item and note 

You might consider placing these statements in the same order in 
which the corresponding text strings occur in the text file. This 
results in the following order of patterns: 


Pattern 

Purpose of statement that includes the pattern 

" A Dafce\:" 

Converts the When date 

" A . " 

Converts the To and From categories 

" A Re\:" 

Converts the item (and note) 


However, if you look at this order you'll see that the generic pattern 
occurs before the pattern " A Re\:". This causes TXT2STF to 
execute the wrong statement for the electronic mail subject line. 
When TXT2STF compares the electronic mail subject line with defini¬ 
tion file statements, it matches the text string "Re:" with the generic 
pattern, and then execute the associated commands, which convert 
To and From categories. 

To correct this problem, put the statement containing the generic pat¬ 
tern at the end of the definition file, which results in the following 
order of patterns: 


Pattern 

Purpose 

" A Date\:" 

Converts the When date 

" A Re\: " 

Converts the item (and note) 

If A . If 

Converts the To and From categories 
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Figure 1-4 shows the actual definition file that formats the sample 
electronic mail message in Figure 1-2. The commands in this defini¬ 
tion file include the arguments necessary to actually convert the sam¬ 
ple electronic mail text file. For more information about definition 
file commands and arguments, see Chapter 5. 


"''DateX: " 

@start {) 

@skip(" +",1) 
©date(W) 


" A Re\:" 

@ custom category( 1 
@skip<" +", 1) 
@item2("$") 

Snote(EOF) 

©end () 

"Messages",,) 

" A .*\:" 

©trim ("" \ N, ' 

"parent") 


©trim("\:N, 1 

"cat") 


@custom_category(cat,parent,) 


Figure 1-4 Sample definition file 


The definition file in Figure 1-4 assumes that your text file contains 
only one electronic mail message, so ©note specifies that the item 
note ends when TXT2STF reaches the end of the text file (specified by 
the argument EOF). If the text file contains more than one electronic 
mail message, you need to change this definition file slightly. (See 
"Creating More Than One Item" in Chapter 7.) 

The definition file is now ready to convert the electronic mail text file 
in Figure 1-2. When TXT2STF uses this definition file to convert the 
electronic mail text file, TXT2STF: 

1. Matches the date line in the electronic mail file with the state¬ 
ment containing the pattern ” A Date\:". 

TXT2STF starts collecting information for a new item. TXT2STF 
then skips over the text string Date: and makes November 17 the 
When date. 

2. Matches the recipient line in the electronic mail file with the 
statement containing the pattern 

TXT2STF puts the string To into the variable called parent, puts 
the name Jill into the variable called cat, and then uses the con¬ 
tents of these variables to create a category. 
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3. Matches the sender line in the electronic mail file with the state¬ 
ment containing the pattern 

TXT2STF puts the string From into the variable called parent, 
puts the name Linda into the variable called cat, and then uses 
the contents of these variables to create a category. 

4. Matches the subject line with the statement containing the pat¬ 
tern " A Re\:”. 

TXT2STF creates the Messages category, and then skips the text 
string Re: and makes the rest of the current line the item text. 

The caret ( A ) in the @item2 command tells TXT2STF to add text 
to the item until it reaches the start of the next line. 

TXT2STF then creates an item note, starting with the line after the 
electronic mail subject line continuing until the end of the file 
(EOF). Finally, TXT2STF ends the item and copies the item, with 
its categories and note, into a structured file. 

After you run TXT2STF to create a structured file, you can import the 
structured file into Agenda whenever you're ready. Figure 1-5 shows 
the converted electronic mail memo after it's imported into Agenda. 


Imported item 
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Figure 1-5 Converted memo text imported into Agenda 


The musical note symbol (J*) beside each item in this view indicates 
that the item has a note associated with it. Figure 1-6 shows the note 
for your imported item. 
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Note for imported item 
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Figure 1-6 Note for the imported item 



Chapter 2 

Creating a Definition File 


You create a definition file to tell TXT2STF how to process text files to 
be imported into Agenda. The definition file must be created before 
it can be used with TXT2STF. 


In this Chapter 

This chapter explains 

• How to create a definition file 

• How to analyze the text file that you plan to import into Agenda 

• How to write the patterns and commands that make up the defini¬ 
tion file 

• How TXT2STF uses the definition file to format a text file 


Creating a Definition File 


When you create a definition file, you perform these general proce¬ 
dures in the following order: 

• Analyze the text file to be structured. 

You must decide how you want to convert the information in your 
text file into items, categories, and notes. 

• Write a definition file to manage the structuring process. 

You write patterns to match specific lines in the text file, and com¬ 
mands to convert the text in those lines to Agenda items, catego¬ 
ries, and notes. 


2-1 
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• Debug the definition file. 

You run TXT2STF with your definition file and determine 
whether it formats information the way you want. If it doesn't, 
revise the definition file and test it again with TXT2STF. 

This chapter provides details about the first two procedures listed 
above. For more information about debugging a definition file, see 
Chapter 7. 


Analyzing the Text File 


Before you write a definition file, you should become familiar with 
the format and contents of the text files that you want to convert. 

You need to analyze your text file to 

• Decide how you want to use information from the text file in 
Agenda. 

You need to determine which text in the text file you want to use 
as items, categories, and/or notes. For example, when converting 
a memo sent through electronic mail, you might want the memo's 
date to be a When date, the names of the sender and recipient of 
the memo to be categories, the subject of the memo to be the item, 
and the body of the memo to be a note for that item. 

• Identify a unique text string for each part of the text file to be 
converted to items, categories, and notes. 

For example, in an electronic mail memo, the memo date might be 
preceded by an identifying label, such as Date. 

• Determine how many types of information the text file contains. 

Check the text file to see whether you have a single type of infor¬ 
mation in the files you plan to convert (for instance, the file con¬ 
tains only memos), or whether you have more than one type of 
information (for example, memos and telexes in the same file). If 
you have more than one type of information, see "Using ©start 
and ©end" later in this chapter. 
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Writing the Definition File Patterns and Commands 


After you analyze the text file to be structured, you can specify the 
patterns and commands that tell TXT2STF how to convert the text 
file. In this way, you construct the definition file. 

You can use any text editor that creates unformatted text files to 
create a definition file. You must give the definition fil e the extension 
.DEF. 


Tip You can write the definition file patterns and commands in an 
Agenda note, and export it to a text file. 


A definition file contains statements that govern the conversion of the 
contents of a text file into a structured file. The statements, and the 
text conversions they produce, are tailored to the requirements of the 
text file. 

For example, a definition file that converts electronic mail files con¬ 
tains different statements from a definition file for files that contain 
legal abstracts due to differences in the layout of the files and in the 
information to be converted. 

Each statement begins with a pattern and can include one or more 
commands: 

• Each pattern describes a line of text to be converted. Each pattern 
is enclosed in a set of double quotation marks (" ") that indicate 
where the pattern begins and ends. The quotation marks are not 
part of the pattern. 

• Each pattern is followed by one or more commands that tell 
TXT2STF how to convert any text line that matches the pattern. 
Each command begins with an at (@) character. 

Guidelines for This section provides guidelines for writing statements in a definition 

Writing Statements file. For specific information about patterns, see Chapter 4. For spe¬ 
cific information about command syntax, see Chapter 5. 

Follow these guidelines when you write definition file statements: 

• To make it easier to differentiate patterns from commands, add 
spaces or tabs after the pattern to separate it from the commands 
that follow it. 


What a 

Definition File 
Contains 




2-4 Creating a Definition File 


If the statement includes multiple commands, you also can add 
spaces or tabs to separate commands from each other on a single 
line. However, consider breaking the statement into multiple 
lines, and lining up commands in a column, as described below. 

• To continue a statement onto another line, break the statement 
between commands. 

This strategy makes it much easier to read and debug statements 
that contain more than one command. 

Note Always break statements between commands; never 
break a statement in the middle of a command. 

• To make it easier to read statements that contain multiple com¬ 
mands, line up commands one under the other in a column. 

Version 1.0 of TXT2STF required you to put a backslash (\) in the 
first column of each continued line in the larger statement. 
Backslashes (\) are no longer required, but you can include them 
in definition files if you want. 

Note The maximum length of a given definition file statement is 
determined by the amount of standard memory available 
when TXT2STF executes to the command. If TXT2STF repeat¬ 
edly encounters memory problems, see if you can shorten 
long statements. 

The definition file in Figure 2-1 follows the above guidelines. 


Patterns Commands 


" A Date\:" 

@start() 



@skip(" + 
@date(W) 

", 1) 

" A Re\:” 

@custom c, 

ategory("Messages", , ) 


@skip(" + 

", 1) 


@item2("$ 

") 


@note(EOF 
@end() 

) 


(atrin^"''” 

, ”\:”,N,"parent") 


@trim("\: 

","$",N,"cat") 


@custom_category(cat,parent,) 


Figure 2-1 Definition file with statements on more than one 
line 
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Including 
Comments in a 
Definition File 


Using @start 
and @end 


The sample definition file in Figure 2-1 contains three statements, 
each of which begins with a pattern and includes commands to pro¬ 
cess text lines. For example, the first statement begins with the pat¬ 
tern " A Date\:" and includes ©start, @skip, and ©date commands. 
Tabs separate patterns and commands in this sample definition file. 
Statements with multiple commands are continued to the next line 
after each command. The commands are lined up in the right hand 
column. 


Comments let you describe what a particular statement or command 
accomplishes and can help you read through the definition file at a 
later time. You add comments for your own use; TXT2STF ignores 
comments when it uses the definition file. 

It is a good idea to 

• Start a definition file with a comment that describes the purpose 
of the definition file 

Since TXT2STF copies the first line of the definition file to the 
structured file, making the first definition file a comment line also 
causes the structured files it creates to start with a descriptive line. 

• Include comments throughout the definition file to describe spe¬ 
cific commands and statements 

Comments that describe specific processing performed by a defi¬ 
nition file can be particularly useful when you debug the defini¬ 
tion file or update it to reflect changes in text file structure. 

To include a comment in your definition file, insert a number sign (#) 
at the beginning of a line. This character must be in the first column 
of the line, or TXT2STF cannot recognize the line as a comment. 

Note Including many lines of comments can occasionally increase 
the time it takes TXT2STF to process your text. 


Each definition file must include at least one pair of ©start and ©end 
commands: 

• ©start sets aside and initializes memory so that TXT2STF can tem¬ 
porarily store information that it converts. 

The patterns and commands that occur after ©start and before 
@end convert text lines and add the resulting structured informa¬ 
tion to memory. The commands executed between each @start 
and @end can create a single item, a note, and any number of 
categories with or without category notes. 
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• ©end bundles together the information in memory and copies it to 
the structured file. 

For example, if memory currently contains two categories and an 
item, ©end assigns the item to the categories and copies them to 
the structured file as a single item specification. After copying 
information to the structured file, ©end initializes memory. 

If the text file contains several occurrences of the same type of infor¬ 
mation, such as several electronic mail messages all formatted in basi¬ 
cally the same way, the same block of definition file commands can 
be executed over and over, each time creating a new item and 
copying it to the structured file. After copying an item to the struc¬ 
tured file, the @end command initializes memory so TXT2STF can 
construct a new item. Then, TXT2STF progresses to the next 
electronic mail message and converts it, starting from the beginning 
of the definition file. 

Figure 2-2 illustrates how ©start and ©end work. If you omit ©start, 
TXT2STF will not have any memory in which to store converted 
information. If you omit ©end, TXT2STF won't put anything in the 
structured file. 

You need more than one ©start or ©end in a definition file when the 
file to be converted: 

• Can begin or end in different ways 

For example, if an electronic mail file can begin with different 
labels, such as either Date: or Today:, you should include a ©start 
for each possible file beginning and an ©end for each possible file 
ending. 

• Can contain more than one type of information 

For example, a text file might include some messages received 
from an internal electronic mail system and some received as telex 
messages. In this case, the messages will have different layouts. 
You must include a ©start and ©end pair for statements that con¬ 
vert the electronic mail messages, and another ©start and ©end 
for statements tailored to convert the telex messages. 

Caution If multiple types of information have patterns in common, 
unexpected structuring can result. 

For more information about ©start and ©end, see "How TXT2STF 
Builds Items, Categories, and Notes" at the end of this chapter. 
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Definition file 


Memory 
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information 


memory 
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TXT2STF to 
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information to be 
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Figure 2-2 How @ start and @end work 


How TXT2STF Uses the Definition File 


To write efficient definition files, it helps to understand how 
TXT2STF uses the definition file when processing your text file. This 
information also helps you when you debug the definition file to 
determine why information in the structured file is different from 
what you expected. 

TXT2STF processes your text file one line at a time, starting with the 
first line in the text file. When it finishes with the current text line, 
TXT2STF proceeds to the next line in the text file. When there are no 
more lines in the text file, TXT2STF stops running. 

The following sections provide details about 
• How TXT2STF processes each line from the text file 
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• How TXT2STF builds items, categories, and notes from text in the 
text file 


How TXT2STF 
Processes Each 
Text Line 


Note TXT2STF always uses standard memory, and not expanded or 
extended memory. 

For each line in the text file, TXT2STF performs the following steps: 

1. Copies a line of the text file into memory 

In this document, this line is often referred to as the current text 
line in memory, or the current text line. 

TXT2STF determines that it has copied the entire text line when it 
encounters a carriage return character (ASCII decimal 13) or the 
alternate separator character as specified by using the TXT2STF 
/S option. (See Chapter 6). The maximum length for a text line 
is 512 characters. 

Caution If a text line is longer, TXT2STF treats it as more than 
one text line, stopping the first line at 512 characters 
and using the remaining characters as a second text 
line. If the current statement ends when TXT2STF is 
only part-way through this second text line, TXT2STF 
discards the unprocessed text characters and contin¬ 
ues to the next unprocessed text line in the text file. 

2. Searches the definition file from the top, looking for a pattern 
that matches the current text line in memory 

As soon as TXT2STF finds a pattern that matches the current text 
line, it stops searching the definition file. (TXT2STF does not 
later search for other patterns that might match the current text 
line.) 

3. Executes the commands associated with the pattern that matched 
the text line, one after the other 

The commands convert the current text line. TXT2STF executes 
all commands associated with the current pattern. When there 
are no more commands for the pattern, TXT2STF continues to 
Step 4. 


TXT2STF processes each text line by copying it into memory, 
searching the definition file for a pattern that matches the line and, if 
it finds a pattern, executing the commands associated with the pat¬ 
tern. 
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1. TXT2STF 
copies a 
line into 
memory 


Text file 



Current line of text 


Next line of text 


Memory 



-- 

Current 


line of 


text 





3. TXT2STF proceeds to the 
next unprocessed text line 
after executing the last command 
in the matching statement. 


Definition file 


START @start 


"current” ^command 
^command 


2. TXT2STF 
searches 
the 

definition 
file for a 
pattern that 
matches the 
current line and 
then executes 
the commands 
in the matching 
statement. 


Figure 2-3 Hozv TXT2STF processes text file lines when 
using a definition file 


How TXT2STF 
Builds Items, 
Categories, 
and Notes 


As TXT2STF processes lines from the text file, TXT2STF formats the 
lines into items, categories, and notes. The commands in your defini¬ 
tion file tell TXT2STF which text to use and which to ignore. 


TXT2STF builds each item, category, and note in a separate buffer in 
memory. These buffers are special portions of the computer's 
memory that only TXT2STF can use. As it builds items, categories, 
and notes, TXT2STF maintains 

• A single item buffer 

• A single note buffer 

• A separate buffer for each category 
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Some commands can also convert subsequent lines from the text 
file. For example, @note can make several consecutive text lines 
into a note. In this case, TXT2STF reads each text line into 
memory, one after the other, and converts it as instructed by the 
command. When the command finishes converting text lines, 
TXT2STF continues to the next command in the statement. 

Note If a command reads additional lines from the text file, 

these additional text lines are not searched and compared 
to other patterns in the definition file as described in 
Steps 1 and 2. 

4. Proceeds to the next unprocessed line in the text file 

In general, depending on the commands you use, the next line in 
the text file is the line immediately after the line most recently 
copied into memory. When it locates the next line in the text file, 
TXT2STF returns to Step 1 above. 

TXT2STF repeats these steps until it has processed the last line from 
the text file. 

Figure 2-3 illustrates the preceding process. The first operation that 
TXT2STF performs on any text line is to copy the line into memory. 
TXT2STF never alters the original text file. 

For more information about how commands influence which line in 
the text file is the next line to be processed, see Chapter 5. For infor¬ 
mation about how to run TXT2STF, see Chapter 6. 
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TXT2STF adds to the end of the appropriate buffer each time it 
executes a command that identifies text to be used as item, category, 
or note text. 

An ©end command causes TXT2STF to bundle together the contents 
of all buffers and then copy the bundled information to the end of the 
structured file. If the item buffer contains text, TXT2STF creates an 
item. If the note buffer or any of the category buffers contain text, 
TXT2STF adds them (it adds the note to the item and assigns the item 
to the categories). 

If the item buffer is empty, TXT2STF can create 

• One or more independent categories (not assigned to items) 

• An independent note (assigned to a blank item on import) 

For example, if the buffers contain two categories and an item, 
TXT2STF adds the item to the structured file, and adds the categories 
as assigned to the item. If the buffers contain three categories but no 
item, TXT2STF creates three categories in the structured file. 

When it copies information to the structured file, TXT2STF inserts 
tags in the converted text that tell Agenda how to import the struc¬ 
tured information, and how to relate various elements. For example, 
tags indicate where each new item starts, and specify the category 
values and notes that belong to each item. (See Appendix B.) 

When TXT2STF terminates, it clears all buffers. It only copies the 
buffers to the structured file if an @end is executed before TXT2STF 
terminates. 

In Figure 2-4, TXT2STF adds converted text to buffers in response to 
commands in the definition file. The @custom_category command 
causes TXT2STF to put a category value in a buffer. Then, TXT2STF 
puts item text in a buffer in response to the @item2 command. When 
TXT2STF executes the ©note command in a later statement, it puts 
note text in a buffer. When it executes the ©end command, TXT2STF 
copies categories, items, and notes to the structured file. 
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1. TXT2STF converts 
the current line 
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Definition file 
START @start 
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Figure 2-4 TXT2STF uses buffers to store text 
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A text file can contain more than one piece of information to be 
converted. For example, a text file can contain several electronic mail 
messages, each one to be converted to a new item. You must make 
sure TXT2STF executes an @end command for each item to be added 
to the structured file. This means you must use @end to copy 
TXT2STF buffers to the structured file when TXT2STF reaches the end 
of each occurrence of the information type (for example, each new 
electronic mail message). 




Chapter 3 

Using Definition Files 


This chapter shows how you can use definition files by providing 
some examples. You can adapt these examples for your use, chang¬ 
ing patterns to suit your own text files, and changing commands to 
convert text as appropriate for your needs. 


About this Chapter 


This chapter presents detailed examples of how to use definition files 
to 


• Convert electronic mail messages 

• Convert a table of information 

For each example, this chapter describes how text in the text file is 
converted and presents a sample definition file that accomplishes this 
conversion. Each example concludes by showing you how the sam¬ 
ple converted information looks after you import it to Agenda. 

These examples give you a starting point for creating your own defi¬ 
nition files. To become familiar with how definition files work, it is a 
good idea to read through both examples. They help prepare you for 
writing your own definition files. 

When TXT2STF converts a text file, it puts the converted information 
into a structured file, which is the file you actually import into 
Agenda. Because reading through structured files requires some 
practice, this chapter omits the structured files from the examples. 
This helps you focus on definition files. When you become more 
familiar with definition files, consult Appendix B for information 
about structured files. Appendix B contains the structured files for 
the examples in this chapter. 


3-1 
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Converting an Electronic Mail Message 


The example described below shows one way to convert a text file 
that contains an electronic mail message. In this example, you'll see 
the original text file to be converted, the definition file that converts 
it, and an Agenda view displaying the converted information after it 
is imported. 


Sample Text File Figure 3-1 shows the text file to be converted. This text file contains a 
generic example of a PROFS® mail message after it is exported to an 
ASCII text file. 

In this example, the electronic mail message will be converted so that 

• The subject of the message (in this example. Charting Seminar!) 
becomes an item 

• The date and time at the top of the message (11 /08/90 15:12:04) 
become an Entry date 

• The sender name (Susan Anthony) becomes a category, with the 
sender's department (Public Relations) as a category note 

Also, the original text file containing the entire electronic mail mes¬ 
sage is attached to the item as a note file. You can do this because 
TXT2STF converts and imports information from text files without 
altering the original text file. When you look at the note in Agenda, 
you see the actual contents of the original text file, since it is used as a 
note file. If you make any changes to the note. Agenda saves the 
changes in the external note file. For more information about note 
files, see Chapter 12 in the User's Guide. 
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1 

From: SG04B04 -LOCKOVM1 Date and time 11/08/90 15:12:04 

To: SG05B05 -LOCKOVM1 ARNOLD BENJAMIN 

From: Susan Anthony, Public Relations 
Subject: Charting Seminar! 

Hi Ben- 

Just when you thought you could work on something besides the Accounting 
Chart package. 

Actually, the reason I am writing you is to do me a favor and possibly earn 
the undying gratitude of the Marketing department at the same time!! 

As you know, (or maybe you don't) - part of my job has me in charge of what 
we are calling Inter-departmental Professional Development - otherwise 
known as training! The Marketing department is trying to enhance their 
leverage on their investment in PCs, so I'm putting together a 2-day session 
on several of the custom applications you've built with the more widely used 
corporate software. 

Hank will be teaching the class. It is being held on November 21st and 22nd 
in the New York office. We would like you to be our guest speaker and do a 
session on the Cloudduster chart portfolio you put together for Accounting. 
(Abby specifically asked for this...I think she wants to use the same approach 
to the quarterly product rollups her group sends to management.) 

Hank is concentrating on the networked ABC pro-forma system and the 
Downfeather application they are using to plan the Q1 Sales Conference in 
Pittsburgh. 

Please let me know as soon as possible if you can come down. We would 
really appreciate your help! 

Sue 


Figure 3-1 Sample electronic mail text file 
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Sample Definition Figure 3-2 shows sample definition file that converts the sample text 
File file shown in Figure 3-1. 


#definition file for electronic mail 

" A *From\:.*Date" @start() 

@skip("Date and time*',l) 
@date(E) 

" A *From\:" @skip("\: ",1) 

@set("save2") 

@trim(i\ (","$",) 

@ category("$ M ,"From", ) 
Sreset(save2) 

@trim( ,,A ” r ”, I \ (",) 
@category_note(" A ") 

" A *Subject\:" @skip{"\: ",1) 

@item(",80,N) 
@note_file(FILENAME) 
@skip_lines(EOF) 

@end () 


Figure 3-2 Definition file for converting the sample 
electronic mail text file 


This definition file contains three statements: 

• The first statement creates the Entry date. 

• The second statement creates a category using the sender name 
and category note using the sender's department. 

• The third statement creates the item and attaches the original text 
file as an item note. 

When the resulting structured file is imported into Agenda, the item 
is assigned to the Entry date and sender name (Susan Anthony) cate¬ 
gories. 

The sample definition file in Figure 3-2 is tailored to work with the 
sample text file shown in Figure 3-1 and might not work with all 
PROFS messages. For example, differences in the header information 
for the message or in how messages are formatted might require 
changes in how the definition file matches and converts text lines. 
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The sample definition file in Figure 3-2 also assumes that each file to 
be processed contains a single electronic mail message, as in the sam¬ 
ple text file. To convert a text file containing multiple electronic mail 
messages, you need to make some changes to the sample definition 
file. For example, you need to change ©note so it specifies something 
other than EOF for the end-of-note string. See "Creating More Than 
One Item" in Chapter 7. 

Creating the Entry date 

The first statement in the sample definition file creates an Entry date. 
This statement begins with the pattern " A *From\:.*Date", which 
matches a text line whose first word is From: and that contains the 
word Date somewhere later in the same text line. To specify this, the 
pattern 

• Starts with a caret ( A ), a special match-control character that speci¬ 
fies that the pattern only matches a string that starts a text line 

• Includes a space () followed by an asterisk (*) 

The asterisk (*) is a match-control character that tells TXT2STF to 
match the immediately preceding character any number of times 
that it occurs in a row. The combination of space () and 
asterisk (*) specifies that the text line can start with any number of 
space characters. 

• Includes FromV 

This tells TXT2STF to match the word From followed by a 
colon (:). The backslash (\) tells TXT2STF that the colon (:) is a 
regular text character (otherwise, the colon (:) starts a special pat¬ 
tern condition). 

• Includes .* 

The period (.) is a match-control character that matches any text 
character, including the space character. The combination of 
period (.) and asterisk (*) tells TXT2STF to match any number of 
text characters. 

• Includes Date 

This tells TXT2STF to match the word Date. Because the pattern 
concludes with this specification, the entire pattern matches a text 
line that starts with From and ends with Date. 

For more information about patterns, see Chapter 4. 
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A pattern and its associated commands together form a single state¬ 
ment. When TXT2STF finds a text line that matches pattern 
"A *From\:.*Date", TXT2STF executes the commands in the 
statement: 

• ©start reserves memory that TXT2STF can use while converting a 
text file into items, categories, and notes. 

• ©skip removes the first portion of the text line, leaving the date 
and time information in the text line 

• ©date makes the remaining current text line into an Entry date (as 
specified by the uppercase E in ©date) 

When Agenda imports the text line, it eliminates extra words, and 
retains only the date and time information as the Entry date. 

For details about definition file commands and the arguments speci¬ 
fied in them, see Chapter 5. 

Creating the sender name category 

The second statement in definition file creates a category from the 
electronic mail sender name (Susan Anthony). This statement begins 
with the pattern " A *From\:", which matches any text line that starts 
with any number of space characters, followed by the word From, 
followed by a colon (:). 

When TXT2STF finds a text line that matches pattern " A *From\:", 
TXT2STF executes the commands in the statement: 

• ©skip deletes the string From:, including the colon (:) from the text 
line. 

To do this, @skip divides the text line into separate values, using 
the colon character followed by a space (\: ) as the dividing 
string. Then ©skip deletes the first value from the field, which is 
everything on the line through the word From, followed by a 
colon (:), followed by a space character. 

• ©set puts the current contents of the text line (after From: is 
deleted) into a variable named save2. 

• ©trim deletes the words Public Relations from the text line, start¬ 
ing with the comma (,) and continuing to the end of the text line. 

To do this, ©trim searches the current text line for either a 
comma (,) or an open (lefthand) parenthesis. If it finds either of 
these characters, ©trim deletes the character and everything after 
it from the text line. 
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The pattern %! \(" tells ©trim to search for either a comma (,) or an 
open (lefthand) parenthesis. The vertical bar (!) tells ©trim to 
search for either of the two characters on either side of the vertical 
bar (!). In this example, @trim searches for either the comma (,), 
which is on the left side of the vertical bar (!) or the open paren¬ 
thesis, which is to the right of the vertical bar (!). (The 
backslash (\) tells TXT2STF to search for the open parenthesis as a 
regular character and to ignore its special meaning in patterns.) 

• ©category makes the current text line (after the end is deleted) 
into a child category of the From category. 

The dollar sign ($) is the end-of-line match-control character. 

Since the dollar sign ($) is specified as a pattern, ©category makes 
the entire current line through the end of the line into a category. 
The second argument in ©category is "From", which is the name 
of the parent category. 

• ©reset replaces the current text line with the contents of the vari¬ 
able save2, which contains the text line as it existed when ©set 
stored the text line in save2, above. 

• ©trim deletes the name Susan Anthony and the comma (,) from 
the text line. 

This ©trim is similar to the ©trim discussed above. The current 
@trim starts from the beginning of the text line, as specified by the 
start-of-line character, the caret ( A ), and deletes everything up to 
the first comma or open (lefthand) parenthesis, as specified by the 
pattern", I \(". 

• @category_note makes the current line into a category note for the 
sender name (Susan Anthony) category. 

The pattern " A " tells @category_note to make everything into a 
category note until it reaches the start of the next line in the text 
file. 

The statement that starts with the pattern " A *From" only processes 
the second line that starts with From in the electronic mail text file. 
This is because the pattern that starts the statement matches the text 
line, and also because the statement is not the first statement in the 
definition file. To see how statement order affects which statement 
matches a text line, let's examine how TXT2STF uses the current defi¬ 
nition file to convert text lines in the text file: 

• TXT2STF starts with the first line in the text file and compares that 
line to patterns in the definition file, starting from the top of the 
definition file and working down. 
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The first line in this text file contains only the number 1, and does 
not match any patterns in the definition file. 

• TXT2STF then moves to the second line in the text file and com¬ 
pares that text line to definition file patterns, starting from the top 
of the definition file and working down. 

The second line starts with From and contains the word Date, so it 
matches the pattern in the first statement, which is 
" A From\:.*Date". The commands in the matching statement for¬ 
mats the text line into an Entry date as described earlier in this 
section. 

• TXT2STF advances line by line through the text file, comparing 
text lines with patterns in the definition file, until TXT2STF 
reaches the second line that starts with the word From. 

This is the next text line that matches a pattern. TXT2STF com¬ 
pares this text line to patterns in the definition file, starting from 
the top of the definition file and working down. Though the text 
line starts with From it does not contain the string Date, and so 
does not match the first pattern in the definition file 
(" A From\:.*Date"), but matches the second pattern (" A FromV"). 
TXT2STF then processes the text line using the commands in the 
statement with pattern " A FromV". 

If the statement with pattern " A FromV", which matches any text line 

that starts with From, were the first statement in the definition pat¬ 
tern, both text lines that start with From would match this pattern: 

• TXT2STF compares the first text line that starts with From with 
patterns in the definition file, starting from the top of the defini¬ 
tion file and working down. 

This text line matches the first pattern in the definition file, 

" A *FromV". Therefore, TXT2STF uses this first statement to pro¬ 
cess the text line, and never compares the text line with pattern 
" A From\:.*Date" since it occurs later in the definition file than the 
matching pattern " A FromV". 

• TXT2STF compares the second text line with patterns in the defini¬ 
tion file, starting from the top of the definition file and working 
down. 

This text line also matches pattern ” *FromV”, and is processed by 
the same definition file statement. 
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Creating the item 

The third statement in the sample definition file creates an item. This 
statement begins with the pattern " A *Subject\: M , which matches any 
text line that starts with any number of space characters, followed by 
the word Subject, followed by a colon (:). 

When TXT2STF finds a text line that matches pattern " A *Subject\:", 
TXT2STF executes the commands in the statement: 

• ©skip deletes the string Subject:, including the colon (:) from the 
text line. 

• @item creates a note from the remaining text on the text line. 

The pattern " A " tells ©item to make an item that includes all text 
up to the start of the next text line. 80 specifies that the item can 
include a maximum of 80 characters. The N tells @item to not put 
any remaining characters from the text line (if any) in a note for 
the item. 

Note @item2 is an alternative to ©item. The equivalent @item2 
argument list would be @item2("$",80,N). For more infor¬ 
mation, see Chapter 5. 

• @note_file attaches the current text file, which contains the elec¬ 
tronic mail message, as a note file for the current item. 

FILENAME is a predefined variable that tells @note_file to use the 
current text file name as the note file name. 

• @skip_lines moves TXT2STF to the end of the text file. 

EOF (end of file) is a predefined variable that tells @skip_lines to 
move to the end of the current text file. 

• @end adds the categories, notes, and item created by this defini¬ 
tion file to a structured file. 

©end is the only way to add this information to the structured file, 
which is the file that Agenda can import. If ©end is omitted, the 
structured file won't contain the categories, notes, and item 
created in this example. 

After ©end, the definition file terminates since it is at the end of the 
text file, and there is no more text to convert. 
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After the 
Structured 
File Is 
Imported 


The sample definition file in Figure 3-2 puts the item and categories it 
creates into a structured file. To import the item and categories into 
an Agenda file, you start Agenda and use the File Transfer Import 
command to import the structured file. 

Figure 3-3 shows how the item and categories created by the sample 
definition file look after you import the structured file into Agenda. 
The view in Figure 3-3 shows imported messages. 


Imported item and categories 


. File:. -a:\IHFri. ■ ' 11,■**/*> 4:3C PB1 

View: Imported Message j; ' 

. Imported • From ' EiM-fy 

ti Atrcrnoor wocksh.ip in Auditorium • Lendl . •11/93790 Ll-.Tla 

n Product announcement *>nd demo -ReJcha Chitre ':i;0?/5C 

a RarJvmq SticHfits Nnw Available -MAIH ADMIfJ -11'087 S3 8t21am 


Figure 3-3 The imported item and categories 


The double musical note symbol (J5) before the imported item indi¬ 
cates that the item has an external note file attached to it. In the 
current example, the note file is the text file containing the original 
electronic mail message. If you highlight the Susan Anthony cate¬ 
gory, a musical note symbol (J*) displays in the upper righthand cor¬ 
ner of the screen to indicate that the category also has a note. In this 
example, the note contains the text Public Relations. 


Converting a Table of Information 


The example described below shows one way to convert information 
that is arranged in a table format. This example converts a text file 
that contains a report derived from Lotus CD/Corporate®, a member 
of the Lotus One Source® family of CD-ROM-based information 
products. CD/Corporate provides business news, statistics, and 
financial information through monthly CD-ROMs and online 
updates. 

The report shown in this example was generated and saved (trans¬ 
ferred to an ASCII text file by using CD/Corporate). After saving a 
CD/Corporate report in an ASCII text file, you can use TXT2STF to 
process it. 
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The strategy for converting the table shown in the following example 
applies to any ASCII text file that contains information in a table. For 
example, you could apply this strategy to convert a table of informa¬ 
tion from a Lotus 1-2-3 worksheet that has been printed to a text file. 
Keep in mind, however, that you need to change the definition file 
shown in this chapter to work with your table and your Agenda file 
requirements. 

Note Remember when using TXT2STF to convert tables (as well as 
any other information) is that the information must be in a text 
file (ASCII format). You cannot directly convert a CD/Corpo¬ 
rate report or a 1-2-3 worksheet because they are not in ASCII 
format. You must first create an ASCII text version. For 
CD/Corporate, transfer the report to a text file. For a 1-2-3 
worksheet, print the spreadsheet to a text file. 


Sam pie T ext File The text file for the current example contains information from the 

Lotus CD/Corporate Industry Participants report, which is standard 
CD/Corporate output. This report lists all companies assigned to a 
particular industry grouping, ranked according to sales. 

Figure 3-4 shows the beginning of the sample report derived from 
CD/Corporate. The report has already been saved in a text file, and 
so is already in ASCII format and ready to be converted. The table in 
this report lists companies in the Food Processing industry. The orig¬ 
inal report is long, so Figure 3-4 shows only a portion of the report. 

The sample table in Figure 3-4 will be converted so that 

• The text on the Industry line (Food Processing) is added as a child 
category under the category Industry. 

• The table headings (Rank, Company, FYE, Sales, and Income) 
each become categories. 

• Each company name (for example, Sara Lee Corp) becomes an 
item and is assigned to the Company category. 

• Each company name is assigned to the Rank, FYE, Sales, and 
Income categories by the corresponding date and numeric values 
listed for the company in the table. 
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INDUSTRY PARTICIPANTS 


Industry: Food Processing 


Rank Company 

1 Sara Lee Corp 

2 Conagra Inc 

3 IBP Inc 

4 Archer Daniels Midland Co 

5 Borden Inc 

6 Ralston Purina Co 

7 H J Heinz Co 

8 Quaker Oats Co 

9 Campbell Soup Co 

10 General Mills Inc 

11 CPC International Inc 

12 Kellogg Co 

13 Beatrice Co 

14 Swift Independent Packing Co 

15 Whitman Corp 


FYE 

Sales 

Income 

7/01/89 

11,717,678 

410,492 

5/28/89 

11,340,414 

197,878 

12/31/88 

9,066,101 

62,328 

6/30/89 

7,928,836 

424,673 

12/31/88 

7,243,526 

311,882 

9/30/88 

5,875,900 

387,800 

5/03/89 

5,800,877 

440,230 

6/30/89 

5,724,200 

203,000 

7/30/89 

5,672,100 

13,100 

5/28/89 

5,620,600 

414,300 

12/31/88 

4,700,000 

289,100 

12/31/88 

4,348,800 

480,400 

2/28/89 

4,066,000 

325,000 

10/31/87 

3,692,147 

-18,437 

12/31/88 

3,582,500 

233,500 


Figure 3-4 Sample text file containing information in a table 


The table shown in Figure 3-4 is slightly different from the original 
table. In the original table, the column heads spanned two lines 
rather than one, and the heads were separated from information by a 

line of dashes (-). For example, the beginning of the table looked 

like this: 


Corporate Net 

Rank Company FYE Sales Income 


1 Sara Lee Corp 7/01/89 11,717,678 410,492 


To make the table easier to process: 

• The two-line headings. Corporate Sales and Net Income, were 
shortened so that all headings could fit on a single line. 

• The line of dashes (-) that separated column headings from the 

data was deleted. 

In addition, an extra space was added between the Rank and Com¬ 
pany heads, so that each column head is separated from the next 
column head by at least two space characters. All of these changes 
make it easier to write a ©table command to process the table. 
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Sample Definition Figure 3-5 shows the sample definition file developed for the sample 
File CD/Corporate text file in Figure 3-4. As is typical of definition files, 

this definition file is tailored to work with the sample text file in 
Figure 3-4. This definition file, however can be used for any Industry 
Participants report extracted from CD/Corporate, put into a text file, 
and modified as described in the previous section. 


#_able-reading DFF file sample for CD/Corporare participant table 

"InduslryA :" @start() 

@skipp\: -,1) 

@categoxy"Industry",) 

@end(} 

@skip_lines(1) 

#@table starts in the left, so the argument list stays on one line 
# (required for all commands) 

Stable ('• +",EOF, 1, "unindexed", 2, "item", 3, "dato", 4, "mimeric", 5, "numeric") 


Figure 3-5 Definition file for converting the sample table 


The sample definition file in Figure 3-5 contains a single statement 
that starts with the pattern "Industry When TXT2STF finds a text 
line that contains the word Industry followed by a colon (:), it 
executes the commands in the statement. 

The statement first executes a ©start to reserve memory for TXT2STF 
to use while converting the text file. Next, remaining commands 
process the sample text file, starting with the text line that contains 
the word Industry. 

Commands in the statement 

• Create a category from the industry (in this example. Food Pro¬ 
cessing) listed in the Industry text line 

• Process each row in the table 

Creating the Food Processing category 

The definition file statement creates a Food Processing category as a 
child of the category Industry. The statement executes the following 
commands: 

• ©skip deletes the word Industry and the colon (:) that follows it 
from the text line. 
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To do this, ©skip divides the text line into separate values, using 
the colon (:) followed by a space () as the dividing string. The 
backslash (\) before the colon (:) tells ©skip to use the colon (:) as 
a regular text character (otherwise the colon (:) starts a special pat¬ 
tern condition). Then ©skip deletes the first value from the field, 
which is everything on the line through the colon (:). 

• ©category makes the current text line (after the word Industry and 
the colon (:) are deleted) into a child category of Industry. 

The pattern "$" tells ©category to make the entire current line 
through the end of the line into a category. The second argument 
in ©category is "Industry", which is the name of the parent cate¬ 
gory. 

• ©end saves the category to the structured file. 

It is important to execute an @end before starting to process a 
table since the first thing the ©table command does is clear the 
memory where items and categories are saved prior to being 
copied to the structured file. If this ©end is omitted, the struc¬ 
tured file won't contain the Food Processing category. 

Since there are unprocessed text lines in the text file after the Industry 
line, TXT2STF continues processing the text file after executing ©end. 

Processing the table 

In order to process the table in Figure 3-4 and create items and cate¬ 
gories, the definition file statement in Figure 3-5 executes the follow¬ 
ing commands: 

• ©skipjines skips over the blank line between the Industry line 
and the table. 

• ©table processes each line in the table, creating categories from 
the first line in the table and creating items from remaining lines. 

©table is a powerful command. The single ©table command in 
Figure 3-5: 

• Processes the row containing table headings to create categories, 
making Rank an unindexed category, Company a standard cate¬ 
gory, FYE a date category. Sales a numeric category, and Income a 
numeric category 

• Processes each line in the table, creating an item from the com¬ 
pany name and making date and numeric values in the same rows 
into category assignments for the item 
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When the resulting structured file is imported into Agenda, each 
item is assigned to the Company category and is also assigned by 
date/numeric value to the Rank, FYE, Sales, and Income catego¬ 
ries. 

©table converts a table one line at a time, ©table assumes that the 
first line in a table provides header or label information for each col¬ 
umn, and so always starts by making text in the first table line into 
categories. Then ©table converts the remaining text lines, creating an 
item and related categories from each text line. To do this, ©table 
includes the following arguments: 


Argument 

What it specifies 

" +" 

The pattern that ©table uses to divide each text line into 
table columns. This pattern tells ©table to end each column 
when it finds tzvo or more spaces in the text line. This is why 
an extra space was added between the original Rank and 
Company headings (described earlier in this chapter). 

EOF 

The end of the table, ©table finishes processing text lines 
when it reaches the end of the text file (EOF stands for 
end-of-file). 

l,”unindexed" 

How ©table converts text in the first table column. In this 
case, the first column contains information for an unindexed 
category (Rank). 

2,"item" 

How @table converts text in the second table column. In this 
case, the second column contains items. 

3,"date” 

How ©table converts text in the third table column. In this 
case, the third column contains information for a date cate¬ 
gory (FYE). 

4, "numeric" 

How ©table converts text in the fourth table column. In this 
case, the fourth column contains information for a numeric 
category (Sales). 

5,"numeric" 

How ©table converts text in the fifth table column. In this 
case, the fifth column contains information for a numeric 
category (Income). 


When it starts processing each text line, ©table internally executes 
©start to clear the memory where ©table adds items and categories as 
it creates them. After it processes each text line, ©table internally 
executes ©end to add the current item and category information to 
the structured file. Then ©table continues to the next line in the table. 
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After the 
Structured 
File Is 
Imported 


The definition file puts the items and categories it creates from the 
table of food processing company information into a structured file. 
To import the items and categories into an Agenda file, you start 
Agenda and use the File Transfer Import command to import the 
structured file. 

Figure 3-6 shows how the items and categories converted in this 
example look after you imported the structured file into Agenda. The 
view shown in Figure 3-6 displays the names of companies, their rela¬ 
tive ranking in the industry, their fiscal year end dates, and their sales 
and income figures. 



Figure 3-6 The imported items and categories 



Chapter 4 
Patterns 


A pattern describes a string of text characters. The pattern specifies, 
character by character, the text string to match. The pattern also can 
include additional information about the text string, such as whether 
it starts or ends the text line. 


In this Chapter 


This chapter gives you information about how to use patterns by 

• Describing how to use patterns in definition files 

• Describing special patterns START and END that you can use 
with TXT2STF 

• Detailing the match-control characters you can use when con¬ 
structing patterns 

• Detailing how TXT2STF uses patterns to match text strings in text 
lines 


About Patterns 


Patterns describe text strings in a text file. Whenever you need to 
match a text string in a text file, you specify a pattern in the definition 
file. 

You use patterns in the following ways: 

• You begin each definition file statement with a pattern that 

describes the text line where the statement begins converting text. 


4-1 
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When TXT2STF finds a text line that matches the pattern, 

TXT2STF converts the text line by executing the commands in the 
statement. 

• You also can include patterns as arguments in many definition file 
commands. 

For example, you can include a pattern in ©replace to identify the 
text string to be replaced with another string. When TXT2STF 
finds the identified string in the text line, it replaces it with the 
substitute string also specified by ©replace. 

A pattern describes a text string. To create a pattern, you can 

• Type the text string itself, surrounded by a pair of double quota¬ 
tion marks (”"); you must use double quotation marks (”") and not 
single quotation marks (''). 

For example, to search for the text string Subject, use the pattern 
"Subject". If the text string includes spaces, make sure the pattern 
specifies each space in the correct position. Do not add spaces 
where the text line has no spaces. 

• Include match-control characters in the pattern. 

Match-control characters help provide extra information about the 
text string in a compact form. For example, match-control charac¬ 
ters let you specify whether the text string is the first or last text on 
a line. You also can use match-control characters to specify a 
more generic pattern, such as a pattern that matches any grouping 
of four letter characters in a row. 

For more information, see "Match-Control Characters" later in this 
chapter. 

Note TXT2STF ignores case when matching letters of the alphabet, 
unless you specify the /C option when you run TXT2STF. 

(See Chapter 6.) 


Special Patterns 


TXT2STF provides two special patterns, START and END, that iden¬ 
tify the beginning and the end of a text file. These patterns can begin 
definition file statements. They cannot be included as patterns in 
commands. Do not enclose the patterns START and END in quota¬ 
tion marks. 



Patterns 4-3 


START 


END 


Using START 
and END 


Note Do not confuse these patterns with ©start and ©end, which 
are commands. (See Chapter 5.) You can, however, include 
©start in a statement that begins with START and ©end in a 
statement that begins with END. 


START causes a statement to execute only once, when TXT2STF 
begins processing the text file. You use START when the statement 
includes commands you want TXT2STF to run only when it begins 
processing the text file. 

You can also use START to write a statement that specifies the format 
of dates in the structured file. Agenda uses this information when it 
imports the structured file. Use START as the pattern and put the 
@date_format command in the statement, followed by an @end com¬ 
mand. @date_format specifies the format of numeric dates in the 
structured file (for example, MM/DD/YY format). 


END causes a statement to execute only once, when TXT2STF finishes 
processing the text file. You use END when the statement includes 
commands you want TXT2STF to execute only when it finishes pro¬ 
cessing the text file. 


You might use START and END if you have a group of files that 
don't all start and/or end in the same way. Use START as the pattern 
in the statement that contains the first ©start command. Use END as 
the pattern in the statement that contains the final ©end command. 

You should not use END as the only pattern associated with the ©end 
command if your input text file has more than one input group, for 
example, a number of electronic mail messages, each one of which 
should become a separate item. You need an ©end command to copy 
each item to the structured file; if ©end is not executed until TXT2STF 
doses the file, only the last item is copied to the structured file. 

START and END do not cause TXT2STF to read text into memory, so 
you should only use them with commands that do not make use of 
the current text line, such as ©start, ©end, and @date_format. 

Note You should not use these patterns in commands that convert 
text into items, categories, or notes, as those commands 
require that you have a text line in memory to be converted. 
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Match-Control Characters 


Match-control characters let you write patterns that match a varied 
set of text strings in the text line by letting you specify additional 
information about the text strings to be matched. 

For example, to match lines that start with the word Subject, begin 
the pattern with the caret ( A ) match-control character. Caret ( A ) tells 
TXT2STF to find the specified text string only when it occurs at the 
beginning of a line, resulting in the pattern " A Subject M . To search for 
a line starting with either Subject or Re, you could use the pattern 
" A (Subject! Re)’’, which includes the vertical bar (!) as the "or" charac¬ 
ter. 

The following table summarizes the available patterns. Each 
match-control character is discussed in greater detail later in this 
chapter. 


Note These match-control characters are different from the match- 
control characters used in Agenda for text conditions. 


Match-Control Character 

Description 

Asterisk (*) 

Matches zero or more occurrences of the preceding 
pattern character 

Backslash (\) 

Specifies that the next character in a pattern is a 
text character and not a match-control character 

Brackets ([]) 

Specifies a range or group of characters, and 
matches any single text character specified in the 
range or group 

Caret ( A ) 

As the first character in a pattern, causes the pat¬ 
tern to match the corresponding text only when it 
occurs at the beginning of a text line 


As the first character in a pair of brackets ([ I), 
caret ( A ) negates the range or group specified in 
the brackets 

Colon a (:a) 

Matches any single uppercase or lowercase alpha¬ 
betic text character 

Colon d (:d) 

Matches any single numeric text character from 0 
through 9 

Colon n (:n) 

Matches any single alphabetic or numeric text 
character 


continued 
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Asterisk (*) 


Match-Control Character Description 

Colon space (: ) 

Matches a single space or control character in the 
text file 

Dollar sign ($) 

As the last character of a pattern, causes the pat¬ 
tern to match the corresponding text string only 
when it occurs at the end of a text line 

Parentheses () 

Groups pattern characters into a string so you can 
apply a match-control character to the string 

Period (.) 

Matches any single character in the text file (except 
a carriage return or linefeed character) 

Plus (+) 

Matches one or more occurrences of the immedi¬ 
ately preceding pattern character 

Tilde (~) 

Matches any text string that is not the pattern 

Vertical bar (j) 

Matches one pattern or another (performs a logical 
OR) 

The asterisk (*) matches zero or more occurrences of the preceding 
pattern character. For example, "X*" matches a zero, one, or any 
number of uppercase X characters in a row. 

To match zero or more occurrences of a string, enclose the entire 
string in parentheses, followed by the asterisk (*). 

Tip If you need to match at least one text character, use the plus (+) 
and not the asterisk (*). 

Examples 


Sample pattern 

Matches in the text file 

"ab*" 

a 

ab 

abbbb 


It does not match zb or fbbb 

"Hey{, Terry)*" 

Hey 

Hey, Terry 

Hey, Terry, Terry, Terry 


For more examples of using the asterisk (*), see the section about the 
period (.) later in this chapter. For more information about how 
TXT2STF matches the asterisk (*), see "How TXT2STF Compares Pat¬ 
terns with Strings" later in this chapter. 
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Backslash (\) The backslash (\) specifies that the immediately-following character 

is a text character and not a match-control character. You use the 
backslash (\) to match a character that TXT2STF uses as a match- 
control character, such as the asterisk (*) or dollar sign ($). 

For example, to match the string "Amount in US$", you need to 
match the dollar sign ($) as a text character. To do this, use the fol¬ 
lowing pattern: "Amount in US\$". The backslash (\) in this pattern 
tells TXT2STF to match the dollar sign ($) as a text character, and to 
ignore its special meaning as the end-of-line match-control character. 

Use backslash (\) before each of these special characters to match 
them as literal text characters: 

*.~:][ A $\! 1 ) ( # @ " 

The backslash (\) applies to only one character at a time. To match a 
string of special characters as literal text, you must precede each of the 
special characters with a backslash (\). 

Tip The backslash (\) cannot be used for control characters (ASCII 
decimal 1 through 32). To match these characters, use the 
combination of colon (:) and space ( ), described later in this 
chapter. 


Examples 

Sample pattern 

Matches in the text pie 


Two consecutive dollar signs ($$) in the text file 

"Coll\\Col2" 

The string Coll\Col2 


Brackets 

(□) 


Brackets ([ ]) define a range or group of characters, and match any 
single character in that range or group. You can include range and 
group specifications in the same pair of brackets ([ ]). 

You can specify any text characters (characters above ASCII 031), 
including the space character ( ). 

Note TXT2STF ignores the / C option when matching characters 
specified in brackets (ID, and matches those characters 
exactly as specified in the range or group. 

Ranges 

A range is a contiguous set of characters or values, for example 1 
through 5. You specify a range to match any one of the characters in 
the range. 
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To specify a range, identify the lowest and highest values in the 
range, separating these values with a hyphen (-). For example, [1-5] 
matches any character in the range from 1 through 5. [a-z] matches 
any single lowercase character in the range from a through z. 

The characters that define the range must be specified with the 
smaller ASCII decimal value first and the highest ASCII decimal 
value last. Use the standard character representation (for example, A 
or 9) and not the equivalent ASCII decimal representation. 


Examples 

Sample pattern 

Matches in the text file 

" [A-Z] " 

Any single uppercase letter 

"[a-zA-Z]" 

Any single character in the alphabet, including both upper¬ 
case and lowercase values 

"[0-9]" 

Any single numeric character from 0 to 9, including 0 and 9 

"[a-c5-9]" 

Any single character in the alphabetic range of lowercase a 
through c or in the numeric range 5 through 9 


Groups 

A group is a list of characters, each of which is valid. You specify a 
group of characters to match any one of a specific list of characters. 


Examples 

Sample pattern 

Matches in the text file 

" [SML] " 

Any of the uppercase characters S, M, or L 

" [RGB] " 

Any of the uppercase characters R, G, or B 

"[a-z!23]" 

Any of the lowercase characters specified in the range a 
through z, or any of the numbers 1,2, or 3 


Special character guidelines 

A match-control character that immediately follows a range or group 
applies to the entire range or group. For example, [A-Z]+ matches 
one or more characters in the range A through Z. 
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Caret ( A ) 


When included inside of brackets ([ ]) 

• Match-control characters lose their special meaning when 
included in range or group specifications. For example, the 
asterisk (*), backslash (\), period (.), and left bracket ([) represent 
actual characters when included in a pair of brackets ([ ]). 

• The caret ( A ) negates the remaining specification when included 
as the first character inside the brackets (l ]). The pattern 
matches any character except a character specified in the range or 
group. The pattern does not, however, match linefeed (ASCII dec¬ 
imal 10) or carriage return (ASCII decimal 13). 

• The hyphen (-) indicates a range specification unless it occurs as 
the first character after the left bracket ([), or after the caret ( A ) in 
negative patterns. In these two cases, the hyphen (-) is an actual 
character and not a special character. 

• The right bracket (]) ends the range or group specification unless 
it occurs as the first character after the left bracket ([), or after the 
caret ( A ) in negative patterns. In these two cases, the right 
bracket (]) is an actual character and not a special character. 


Examples 


Sample pattern 

Matches in the text file 

"[a-zA-Z]+" 

One or more alphabetic characters, uppercase or lowercase, 
in a row 

"[ A 0-5]" 

Any character that is not in the range 0 through 5; for 
example, it matches A or 6, but does not match 5 

"[^XYZ]" 

Any character that is not an uppercase X, Y, or Z; for 
example, it matches A, 1, and lowercase x, y, or z 

" [] 1~7] " 

Either the right bracket (1) or any character in the range 1 
through 7 


Any character in the range from the asterisk (*), which is 
ASCII decimal 042, through the slash (/), which is ASCII 
decimal 47 


The caret ( A ), when included as the first character of a pattern, causes 
the pattern to match the corresponding text string only when it 
occurs at the beginning of a text line. The caret ( A ) must be the first 
character in the pattern. 

To match the caret ( A ) as a normal text character, precede it with a 
backslash (\). 
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Colon a (:a) 


When the caret ( A ) is the first character in a pair of brackets ([ ]), as 
in "l A l-9], the caret ( A ) negates the range or group specified in the 
brackets ([ ]). For more information, see "Brackets ([ ])" earlier in 
this chapter. 

Example 

Sample pattern Matches in the text file 


" A The " Any line that begins with the string The 

It does not match either of these lines: 

1. The 

However, the... 

” A (T°\ : ■ From\ :) Any line that begins with either To: or From: 


For more information about how TXT2STF matches the caret ( A ), see 
"How TXT2STF Compares Patterns with Strings" later in this chapter. 


The combination :a matches any single uppercase or lowercase alpha¬ 
betic character. 

Example 

Sample pattern Matches in the text file 


" :a" W 

z 
B 

or any other single alphabetic character 

Note The :a match-control character is not case sensitive even if you 
use the /C option when you run TXT2STF. (See Chapter 6.) 
To match only uppercase or only lowercase characters, see 
"Brackets ([ ])" earlier in this chapter. 
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Colon d (:d) 


Colon n (:n) 


Colon Space (: ) 


The combination :d matches any single numeric character from 0 to 9. 
Examples 

Sample pattern _ Matches in the text file ~~ ~ 


:d:d:d- :d:d:d:d" 555-8500 

555-1212 

or any other seven-digit phone number with a 
hyphen in the middle 


" Order\: : d: d: d" The word Order, followed by a colon (:), followed 

__by any three-digit order number 


The combination :n matches any single uppercase or lowercase alpha¬ 
betic character or numeric character. 

Example 


Sample pattern 

Matches in the text file 

":n:n:n" 

b5h 

897 

XXX 

or any other combination of three alphabetic and/or 
numeric characters 


The combination of colon (:) followed by one space ( ) matches one 
space or control character. 

Specifically, it matches any character from ASCII decimal 1 
through 32. This list includes tab (ASCII decimal 9), linefeed (ASCII 
decimal 10), carriage return (ASCII decimal 13), and other control 
characters as well as the standard space ( ) character (ASCII 
decimal 32). 

Example 

Sample pattern Matches in the text file 


Any two-character combination consisting of a single 
numeric character followed by one space or control 
character, such as tab 
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Dollar Sign ($) 


Parentheses () 


The dollar sign ($), when included as the last character of a pattern, 
causes the pattern to match the corresponding text string only when 
it occurs at the end of a text line. The dollar sign ($) matches the 
actual end of a line (not the carriage return, linefeed, or alternate 
separator). 

To use the dollar sign ($) as a normal text character, precede it with a 
backslash (\), 


Example 


Sample pattern 

Matches in the text file 

"The end.: *$" 

Any line that ends with The end 


It does not match a line that ends with: 

The end. Display film credits. 


For more information about how TXT2STF matches the dollar 
sign ($), see "How TXT2STF Compares Patterns with Strings" later in 
this chapter. 


Parentheses group characters into a string. This lets you apply a 
match-control character to an entire string rather than to just a single 
character. 

Each set of parentheses in a pattern begins a new level of nesting. 
When you include a set of parentheses inside another set of paren¬ 
theses, the inner parentheses define a new nesting level that is one 
level deeper than the level defined by the outside set. A pattern can 
include up to 10 nesting levels. If you end one set of parentheses 
before starting a second set, both parentheses are at the same level of 
nesting. 


Examples 


Sample pattern 

Matches in the text file 

” (hlq) *•' 

Zero or more consecutive occurrences of the entire 
string HLQ, for example, HLQhlq 

” (:n:n:n)+" 

A line containing one or more strings of three 
numeric characters, for example 123 

,,A (:a:a{ :d:d)+)+" 

A line starting with two alphabetic characters 
(specified by :a:a) followed an even number of 
numeric characters (specified by :d:d); the string 
can include any number of instances of this string 
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Period (.) 


Plus (+) 


The period (.) matches any single character, including a space charac¬ 
ter. The period (.) also matches control characters (ASCII decimal 1 
through 31, except for linefeed (ASCII decimal 10) or carriage return 
(ASCII decimal 13)). 


Examples 

Sample pattern 

Matches in the text file 

....... 

123 


abc 


0= 


Any characters up to the start of the next new line 


Any characters up to and including the final colon (:) on the 
current line; the pattern does not match a text line if the line 


is missing a colon (:) 


The plus (+) matches one or more occurrences of the immediately- 
preceding character. 


To match one or more occurrences of a character string, enclose the 
string in parentheses followed by plus (+). 


Tip To match zero or more occurrences of a character, use the 
asterisk (*) and not the plus (+). 

Examples 


Sample pattern 

Matches in the text file 


"b+” 

b 

bb 

bbbbbbbb 


"0123+" 

0123 

01233 

012333333333 


" (0123)+" 

0123 

01230123 

0123012301230123 



continued 
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Tilde (~) 


Sample pattern 

Matches in the text file 


All characters up to the start of the next new line; the pattern 
does not match a text line if the text line lacks at least one 
character before a linefeed, carriage return, or alternate sep¬ 
arator character 

".+\:" 

All characters up to and including the final colon (:) on the 
current line; the pattern does not match a text line if the line 
lacks a colon (:) preceded by at least one other character 

For more information about how TXT2STF matches the plus (+), see 
"How TXT2STF Compares Patterns with Strings" later in this chapter. 

The tilde (~) matches any string that is not the pattern. 

Note Negative patterns typically provide less control over what the 
statement matches. As a general rule, use negative patterns 
only in text files in which the order and format of lines is very 
predictable. 

Example 


Sample pattern 

Matches in the text file 

" A -Modem" 

Any line (or string) that does not begin with the word 

Modem 

,,A -. *Modem" 

Any line (or string) that does not contain the word Modem 


Note To make sure that the pattern does not match every line in the 
text file, it is important to anchor the pattern to some fixed 
characteristic in the string you want to match. For example, 
the pattern " A -Modem" matches lines that start with any 
string other than Modem. Without the caret ( A ), this pattern 
would also match lines that include the string Modem, since 
portions of this string (such as odem) are not the same as the 
string Modem, and so would match the pattern. 

For more information about how TXT2STF matches the tilde (~), see 
"How TXT2STF Compares Patterns with Strings" later in this chapter. 
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Vertical Bar ( I ) The vertical bar (!) represents a logical OR. This lets you match one 
pattern OR another. You separate the alternative patterns with the 
vertical bar (!). 

Examples 

Sample pattern Matches in the text file 

"alb" aORb 

"dog ! cat" dog OR cat 

" [ a-f ] ! [q-z ] " Any single letter between a and f OR any single letter 
between q and z 


How TXT2STF Matches Patterns 


TXT2STF compares a pattern to the characters in a text line to deter¬ 
mine whether the text line matches the pattern. TXT2STF searches a 
single text line at a time. If the text line includes the entire string 
specified by the pattern, it matches the pattern. If the text line lacks 
the string, the line does not match the pattern. 


When TXT2STF Patterns describe strings in your text file that you want TXT2STF to 
Matches Patterns match. By matching the string, TXT2STF finds a portion of text that 
you want to convert. 

You use patterns in definition file statements in the following ways: 

• Each definition file statement begins with a pattern that identifies 
the text line the statement converts. 

For example, to convert a text line that includes the string Person¬ 
nel Record, a definition file statement begins with the string "Per¬ 
sonnel Record". 

• You can include patterns as arguments in definition file com¬ 
mands. 

For example, you can specify where an item ends by including a 
termination pattern in the ©item command. 

TXT2STF matches these patterns as described below. 
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Patterns that begin statements 

Patterns that begin statements identify which text lines the com¬ 
mands in the statement convert. 

TXT2STF converts a text file line by line. After reading a line of the 
text file into memory, TXT2STF compares it with patterns in the defi¬ 
nition file, starting with the first pattern in the definition file. The text 
line matches the first pattern that describes a string in the text line. 

For example, the following text line matches the second pattern ("Re¬ 
cords") since TXT2STF encounters the second pattern before the third 
pattern (’^Personnel"): 

Personnel Records For New Employees 

Patterns: 

" A Date\ :" 

"Records" 

"''Personnel" 

When it matches any portion of a text line with a pattern, TXT2STF 
uses the statement that contains the pattern to convert the text line. 
The entire text line is available when TXT2STF executes the first com¬ 
mand in the statement. 

After converting a text line, TXT2STF continues to the next uncon¬ 
verted line in the text file, and attempts to match that line with pat¬ 
terns in the definition file, starting again with the first pattern in the 
definition file. TXT2STF never returns to a converted text line, and 
never uses more than one statement to convert a text line. For more 
information, see "How TXT2STF Processes Each Text Line" in 
Chapter 2. 

Tip If you start TXT2STF with the /M debugging option, TXT2STF 
displays each text string that matches a definition file pattern. 
(See Chapter 7.) Using this information, you can determine 
which text line matches each pattern, and therefore can deter¬ 
mine whether the correct statement converts each text line. 

Patterns that are arguments in commands 

You can include patterns as arguments in definition file commands. 
These patterns are pattern constants that specify information to be 
used in the command. For example, you identify the locations where 
©trim starts and stops trimming text by specifying a start and end 
pattern. 
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When TXT2STF executes a command that includes pattern constants, 
it compares the pattern to the current text line, starting with the first 
character in the line. By matching a string with the pattern, TXT2STF 
navigates to a specific portion of the line. After it locates the appro¬ 
priate place in the text line, TXT2STF performs the operation speci¬ 
fied by the command. 

For example, @trim(" A "," +",) deletes text from the current text line. 
The pattern " A " tells TXT2STF to start deleting at the beginning of the 
text line. The pattern" +" tells TXT2STF to keep deleting text until it 
reaches the end of a string consisting of one or more space characters. 

Note TXT2STF does not display text strings that match pattern con¬ 
stants in commands, even if you start TXT2STF with the /M 
debugging option. 


To see if a text string matches a pattern, TXT2STF compares the char¬ 
acters in the pattern with the characters in the text string, one charac¬ 
ter at a time. A pattern can consist of regular text characters 
exclusively, or can also include match-control characters. 

If the pattern contains text characters, such as the pattern "Subject", 
TXT2STF starts by searching the text line for the first text character in 
the pattern (for example, the uppercase S in "Subject"). When it finds 
that character, TXT2STF compares the next character in the pattern 
(for example, the lowercase u in "Subject") with the next character in 
the text string. If the characters match, TXT2STF continues compar¬ 
ing characters in the pattern with characters in the text line, one by 
one, until the entire pattern matches a complete string. If at least one 
text character in the string differs from the pattern, the text string 
does not match the pattern. 

The TXT2STF /C option determines whether TXT2STF matches or 
ignores the case (uppercase or lowercase) of text characters when it 
matches patterns. (See Chapter 6.) The /C option is ignored, how¬ 
ever, when matching ranges or groups specified in brackets ([ ]). 
TXT2STF matches those characters exactly as they are specified in the 
range or group. 

The caret ( A ) and dollar sign ($) 

Match-control characters affect how TXT2STF matches patterns. 
Specifying a caret ( A ) as the first character in a pattern tells TXT2STF 
to match the pattern only when the corresponding text string begins 
the text line. Specifying a dollar sign ($) as the last character in a pat¬ 
tern tells TXT2STF to match the pattern only when the corresponding 
text string occurs at the end of a text line. 


How TXT2STF 
Compares Patterns 
with Strings 
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The asterisk (*) and plus (+) 

The asterisk (*) and plus (+) tell TXT2STF to match as many occur¬ 
rences of the preceding pattern character as possible. For example, 
"X*" matches zero or more uppercase X characters in a row. The 
pattern matches a string containing zero or more characters. 

When TXT2STF matches a string with a pattern that ends with either 
asterisk (*) or plus (+), TXT2STF matches up through the last text 
character that matches the pattern. If the next character in the pattern 
does not match the next text character after the currently matched 
string, TXT2STF searches backward through the matched string until it 
finds the text character that matches the pattern character. 

For example, the pattern matches a line containing zero or more 
characters, and matches up through the last character in the text line. 
Then, TXT2STF looks to see whether the next character is a colon (:), 
as specified by the combination of backslash and colon (\:) in the 
pattern. Since TXT2STF is at the end of the text line, it cannot find a 
colon after the matched string in the text line. So, TXT2STF starts 
searching backward through the matched string for a colon (:). 

For example, the pattern " A .*V" matches the following sample text 
line up through the colon (:) that ends the word Site: 

From: KGY Site: 23 

To match only up through the colon (:) that ends the word From in 
the above sample text line, you could use the pattern " A [ A :]*\:". This 
pattern matches a string consisting of any characters that are not 
colons (:), as specified by [ A :l*. The string matches the pattern up to 
the first colon in the line or the end of the line, whichever comes first. 
TXT2STF then compares the next character in the text line with the 
next pattern character, which is the colon character specified by the 
combination of backslash and colon (V). If the next character is a 
colon, the text line matches the pattern up through the first colon in 
the line. 

The tilde (~) 

The tilde (~) begins a negative pattern. That is, it tells TXT2STF to 
match any string that is not the pattern. It is important to anchor a 
negative pattern to a fixed characteristic of the text line (for example, 
caret ( A ) anchors the pattern to the beginning of the text line). This 
keeps TXT2STF from trying to match the pattern in ways that, in this 
case, are undesired. 
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To match a negative pattern, TXT2STF starts at the beginning of the 
text line and searches through the entire text line for the negative 
pattern. The negative pattern matches the text line if TXT2STF cannot 
find the negative pattern in the text line. 

The negative pattern does not match the text line if TXT2STF finds the 
negative pattern in the text line. If the larger pattern begins with 
caret ( A ), TXT2STF concludes the matching process and continues to 
the next argument, command, or statement, as appropriate. 

Note Without the caret ( A ) to specify where TXT2STF must begin 
searching the text line, the negative pattern eventually 
matches the text line. Each time TXT2STF finds the negative 
pattern in the text line, TXT2STF moves forward in the text 
line by one character and tries again to locate the negative 
pattern from its new starting location in the text line. Eventu¬ 
ally TXT2STF moves beyond the start of the text string that 
matches the negative pattern. At this point, TXT2STF can no 
longer find the negative pattern in the text line, and so the 
negative pattern matches the text line. 


How TXT2STF 
Searches for 
Character Classes 


Each of the following match-control characters matches any single 
character of a specific type, range, or group: 


• Colon a (:a) matches an alphabetic character. 

• Colon d (:d) matches a numeric character. 

• Colon n (:n) matches an alphabetic or numeric character. 

• Colon space (:) matches a space or control character (ASCII deci¬ 
mal 1 through 32). 

• A range or group specification in brackets ([ ]) matches a charac¬ 
ter specified in the range or group. 

Each of these match-control characters specifies a class of characters, 
any one of which matches the corresponding character in a text line. 
For example, the colon a (:a) combination matches any single upper¬ 
case or lowercase alphabetic character. 
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Before TXT2STF compares patterns with text in the file, it internally 
expands each of these character class specifications, replacing the 
match-control character with the full list of characters it can match. 
For example, TXT2STF internally changes the combination of 
colon a (:a) to the full list of uppercase and lowercase alphabetic char¬ 
acters. Then, TXT2STF compares the text line with the pattern. 

A pattern can include up to eight different character class specifica¬ 
tions: 

• Each group or range specification constitutes a separate character 
class specification. 

• Each different colon combination, such as colon a (:a) or colon 
d (:d), is a separate character class specification. 

The pattern can, however, include any number of the same type of 
colon combination. For example, since all colon a (a:) combina¬ 
tions expand in the same way, TXT2STF can re-use the first 
expanded colon a (:a) specification for all subsequent colon a (:a) 
specifications in the pattern. 


Examples 


This pattern 

Includes these character class 
specifications 

":d:d/:d:d/:d:d" 

One character class specification, for 
the combination colon d (:d) 

”[a-f] ! [q-z] " 

Two character class specifications, one 
for each range 

l,A :a+- :d:d" 

Two character class specifications, one 
for the combination colon a (:a) and 
one for colon d (:d) 

":d:a[3-5abc][3-5abc]:d:a" 

Four character class specifications, one 
for :d, one for :a, and one for each 
range specification (even though they 
specify the same characters) 



Chapter 5 

Definition File Commands 


Agenda provides several commands that you can include in a defini¬ 
tion file to tell TXT2STF how to process the contents of your text file. 


In this Chapter _ 

This chapter describes 

• The types of definition file commands that Agenda offers 

• Definition file command syntax 

• Arguments and variables used with definition file commands 

• The syntax and purpose of each definition file command 

This chapter also includes one or more examples of each definition 
file command. 


About Commands 


Commands tell TXT2STF how to process the contents of your text file. 
For example, commands in your definition file can tell TXT2STF 
when it processes a text file containing electronic mail to make the 
text following Subject: into an item and the text following Date: the 
When date for the item. 

Each definition file statement begins with a pattern, and includes one 
or more commands. A pattern and all of its commands belong to a 
single statement. (See Chapter 2 for more information.) 
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TXT2STF processes a text file by comparing lines in the text file, one 
at a time, with the patterns that begin statements in the definition file, 
starting from the top of the definition file. When TXT2STF matches 
text line with a pattern, TXT2STF executes the commands in the state¬ 
ment whose pattern matches the text line. This is how TXT2STF pro¬ 
cesses the text line. 

Most commands in a statement perform an action that processes the 
current text line. For example, @item2 can take characters from the 
text line and put them into the item buffer, ©skip and ©trim can 
remove text from the text line. When a command finishes processing 
a portion of the text line, the next command in the statement starts 
where the previous line left off. 

So that TXT2STF can progress through a text file, a statement uses up 
at least one text line. When a statement finishes executing, TXT2STF 
gets ready to continue processing the text file by copying the next 
unprocessed text line into memory. Then TXT2STF searches for a 
definition file pattern that matches the current text line in memory. 

Caution Text remaining in the current text line when a statement 
finishes executing is discarded when TXT2STF copies the 
next unprocessed text line into memory in preparation for 
the next statement. 

Commands operate on the current text line in memory, telling 
TXT2STF how to convert the line and whether to save the resulting 
text in the item buffer, a category buffer, or the note buffer. Com¬ 
mands can add text to variables and advance your position in the text 
file. Commands also can tell TXT2STF when to transfer the contents 
of these buffers to the structured file. This chapter describes, for each 
command, the changes the command makes to the current text line, 
to TXT2STF buffers, to variables, to your location in the text file, and 
to the structured file. 

When you include more than one command in a statement, you can 
make the statement easier to read by placing each command on a new 
line, immediately under the preceding command. For example, the 
following statement includes three commands, one under the other, 
beginning with ©start: 

,,A Date\:" @start() 

@skip(" +",1) 

@date(W) 
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Note In Release 1.0, you had to begin each continued command line 
with a backslash (\) as the first character of the new line. The 
backslash (\) is no longer required, but is allowed in defini¬ 
tion files. In this chapter, partial examples where commands 
are shown without the corresponding pattern (or other 
commands) begin with a backslash (\) to indicate that the 
command is part of a larger statement that is not shown. For 
example, a backslash (\) precedes the following ©start since 
the command is shown without a preceding pattern: 

\ @start() 

Agenda definition file commands fall into the following groups: 


• Category commands add categories; each category command 
adds a new category to TXT2STF category buffers. 

• Control commands initialize TXT2STF item, note, and category 
buffers and copy converted text from the buffers to the structured 
file. 

• Date commands add date categories and describe the format of 
numeric dates in the text file. 

• Item commands convert text into items. 

• Note commands convert text into notes for items and categories. 

• Table commands convert tables into items and categories. 

• Trimming commands let you delete text from a text line before 
you convert it. 

• Variable commands create new variables, put values into vari¬ 
ables, and initialize variables. 

The following tables list Agenda definition file commands by group 

and briefly describe the purpose of each command. For more infor¬ 
mation about each command, see the alphabetical description of these 

commands later in this chapter. 
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Category Commands 

Description 

©category 

Creates one or more categories from the text line 
and optionally makes them children of a specified 
parent category 

@custom_category 

Creates a category from text that you specify and 
optionally makes them children of a specified par¬ 
ent category 

©date 

Creates assignments to date categories 

©numeric 

Creates assignments to numeric categories 

©unindexed 

Creates assignments to unindexed categories 


Control Commands 

Description 

©end 

Copies the contents of the item, note, and category 
buffers to the structured file, and then initialize the 
buffers 

©start 

Initializes the item, note, and category buffers 
without first copying them to the structured file; 
prepares the buffers for use 


Date Command 

Description 

©date 

Creates assignments to date categories 

@date_format 

Describes the format of the dates in the text file 


Item Commands 

Description 

@append_item 

Appends a string to the end of the item currently 
being constructed from the text file 

©item 

Creates an item using text from the text file; is an 
alternative to @item2 

@item2 

Creates an item using text from the text file; is an 
alternative to ©item 
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Note Commands 

Description 

©appendnote 

Appends a string to the end of the current note 

@category_note 

Creates a category note and assigns it to the cate¬ 
gory created by the most recently executed ©cate¬ 
gory or @custom_category command 

@category_note_file 

Identifies the external note file for the current cate¬ 
gory 

@make_extemal_note 

Creates an external note file and copies text from 
the text file into the file; on import the note file is 
added as an item note 

©note 

Creates a note and assigns it to the current item 

@note_file 

Identifies the external note file for the current item 



Table Command 

Description 

©table 

Makes information in a table into items and cate- 


gories 


Trimming Commands 

Description 


©replace 

Substitutes one string for another 

©skip 

Divides the line into values and then deletes one 
value from the line 

@skip_lines 

Skips over the number of lines you specify 

©strip 

Deletes one or more occurrences of a specified 
string from the text line 

©trim 

Deletes all the text between one string and 
another, placing the deleted text in a variable 
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Command Syntax 


Variable Commands 

Description 

©append 

Adds a string to the end of the current contents of the 
variable 

©equate 

Stores a pattern or a text string in a variable 

©grab 

Divides the current text line into several values and 
puts each value into a variable 

©reset 

Replaces the current text line with the specified value 

©set 

Stores the current text line in the specified variable 

©trim 

Deletes all the text between one string and another, 
placing the deleted text in a variable 


Each definition file command consists of a keyword, which is the 
command name. Most commands also require you to specify one or 
more arguments in parentheses. Arguments provide the information 
that TXT2STF needs to complete the command; the what and where 
of a particular action. 

Syntax 

Figure 5-1 shows the format for definition file commands: 


©KEYWORD () 

I 

Parentheses 

©KEYWORD (argumentl,argument2,...) 

' I J 

Argument separators 

Figure 5-1 Definition file command syntax 


When you specify a command without arguments, be sure to include 
the pair of parentheses at the end of the command without any 
intervening spaces. 
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Conventions 

This chapter uses these conventions when showing command syntax: 

• Arguments that you replace with your own information are in 
italic type. 

• Optional arguments are enclosed in brackets ([ ]) in the syntax. 

If you omit an optional argument, include the comma (,) that pre¬ 
cedes the argument only if the comma (,) precedes the 
brackets ([]) in the syntax. 

• A pair of double quotation marks (" ") around an argument indi¬ 
cate that the quotation marks are required; you must use a pair of 
double quotation marks (" ") and not a pair of single quotation 
marks (''). 

• Ellipsis points (...) in commands indicate that you can specify the 
argument more than one time. 

Note In examples, vertical ellipses (a series of points, one above 
the other) indicate that lines are omitted to simplify the 
example, as shown below: 

" A Start_trans\:" @start() 

" a QUOTE " @item2("$") 

At (@) character 

Each definition file command starts with an at (@) character. Start the 
command name immediately after the at (@) character without an 
intervening space. For example, use @start(), not @ start(). 

Note Though definition file commands begin with the at (@) char¬ 
acter, they differ from Lotus 1-2-3 at (@) functions, and per¬ 
form different types of processing. 

Keywords 

The keyword in the command is like an action verb. It tells TXT2STF 
what action to perform. 

Arguments 

Arguments provide the information that Agenda needs to complete 
the command. For example, you specify the name of a date category, 
such as When, as an argument in a ©date command to assign a date 
to that category. 
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About Arguments 


Arguments in command syntax stand for specific types of informa¬ 
tion that you can include in the command. 

Follow these guidelines when including arguments in commands: 

• Enclose all command arguments in the pair of parentheses that 
follows the command. 

• Separate the arguments with commas. You can include spaces 
after the commas that separate arguments — for example, 
@skip("\:", 1). 

• If you omit an optional argument (indicated by brackets in syn¬ 
tax), you must still include the correct number of commas in the 
correct places. For example, the following @item2 command 
omits the optional second argument: 

@item2 (" A ",) 

Depending on the command, an argument can be any of the follow¬ 
ing six types: 


Argument 

Type 

Description 

Example 

String 

constant 

A group of characters, 
such as the text of an 
item or a date value. 

A string contains stan¬ 
dard alphabetic, 
numeric, and 
punctuation characters. 

In @append_item("Derived from 
E-Mail" ), the phrase "Derived from 
E-Mail" is a string that the ©appendj- 
tem command adds, without quotes, 
to the end of the current item. 


The backslash (\) is a 
special character that 
instructs TXT2STF to 
ignore the next charac¬ 
ter. 



String constants must 
be enclosed in a pair of 
quotation marks (""). 



continued 
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Argument 

Type 

Description 

Example 

File name 

string 

constant 

The name of a DOS file 
or directory. 

A file name string con¬ 
stant contains standard 
alphabetic characters. 
There are no special 
characters for file name 
string constants. 

In @make_external note 
(" \ agenda "), the phrase 
"\agenda" is the file name string 
constant that names the direc¬ 
tory where 

@make_external_note stores a 
note. 

Variable name 

string 

constant 

File name string con¬ 
stants must be enclosed 
in a pair of quotation 
marks (""). 

The name of a variable. 

A variable name string 
constant defines a vari¬ 
able or references it by 
name. 

In @ append(”de st var", 
source_var) , the phrase 
"dest_var" is the name of the 
variable into which text is 
appended. 


A variable name string 
contains standard 
alphabetic characters. 
There are no special 
characters for variable 
name string constants. 



Variable name string 
constants must be 
enclosed in a pair of 
quotation marks (""). 



continued 
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Argument 

Type 

Description 

Pattern 

constant 

A group of characters 
that describes a string 
for which to search. 


A pattern can include 
standard string charac¬ 
ters and special pattern- 
matching characters, 
such as the 
backslash (\) or 
asterisk (*). (See 

Chapter 4.) 


Patterns must be 
enclosed in a pair of 
quotation marks (""). 

Numeric 

constant 

A number; this value 
cannot contain non¬ 
numeric characters. 

Type 

constant 

A constant that identi¬ 
fies a type of category. 


Type constant can be 
"date", "exclusive”, "nu¬ 
meric", "standard”, 
"unindexed", or (©table 
only) "item". The type 
constant must be 
enclosed in a pair of 
quotation marks (" "). 

Logical 

constant 

A constant that speci¬ 
fies either N (no) or Y 
(yes). Command 
syntax shows these con¬ 
stants as N (italic 
uppercase N). 


Example 


In ©note (" A -*"), the pattern " A - 

—describes the string that signals the 
end of note text in the text file; in this 
case, a text line starting with at least 
three hyphens. 


In @skip_lines (3) , the number 3 
specifies that TXT2STF should skip 
down three lines in the text file. 

In ©category(",","Target 
Dates\: ", "date") , the "date" type 
constant instructs ©category to make 
categories into dates. 


In @trim(" A Who", "How 
Many" , N) , logical constant N 
instructs ©trim to not trim the search 
strings Who and How Many when 
trimming the text between these 
strings. 


continued 
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Argument 

Type 

Description 

Example 

Variable 

The name of a variable, 
without surrounding 
quotation marks. 

A variable name, with¬ 
out quotation marks, 
tells TXT2STF to use the 
contents of a variable. 

In @ append ("dest var", 
source_var) , source._var is the vari¬ 
able whose contents are copied into 
variable dest_var. 


Variables can be used 
in the place of string 
constants, file name 
strings constants, and 
pattern constants. 



Variables cannot be 
used in place of vari¬ 
able name string con¬ 
stants, numeric 
constants, type 
constants, or logical 
constants. 



About Variables 


You can specify variables as arguments in many definition file com¬ 
mands. You can use variables in commands to: 

• Store text from one text line for use in a command that converts a 
later text line. 

• Equate a long pattern to a short variable name and then specify 
the variable in your commands. This can make your definition 
file easier to read. 

Note Variables can only be used as arguments for commands. You 
cannot use variables to represent the patterns that begin state¬ 
ments. 

To create variables and store information in them, use variable com¬ 
mands. A variable can contain a maximum of 512 characters at a 
time. 
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Specifying 
Variables in 
Commands 


Predefined 

Variables 


A variable name can be up to 32 characters in length. Variable names 
can be more than one word and can include spaces. Variable names 
cannot include punctuation and cannot begin with a number. 
TXT2STF ignores the case of a variable when using it. This means 
that you can specify a variable using uppercase, lowercase, or a 
combination of the two. 

When you identify a variable in a command 

• Enclose a variable name in a pair of quotation marks (" ") when 
you need to simply name the variable. 

For example, you name a variable in ©equate to associate the vari¬ 
able name with a specified value. To associate the string 
SOURCE-QIO-A with the variable Origin, you specify 
©equateC’Origin’V’SOURCE-QIO-A"). 

• Specify the variable name without quotation marks when you 
want TXT2STF to use the contents of the variable. 

For example, to append the contents of the Namel variable to the 
end of an item, specify @append_item(Namel). 


Agenda supplies six variables whose values are predefined by 
Agenda: FILENAME, EOF, CR, D, E, and W. You can use these 
variables anywhere you need to use the Agenda-defined value. 
TXT2STF ignores the case of these variables. This means you can use 
uppercase, lowercase, or a combination of the two when naming any 
of these variables. 

FILENAME 

You can use FILENAME in commands to stand for the current text 
file name. For example, you can use this variable in @custom_cate- 
gory to assign each item to a category whose name is the file from 
which the item came. 

As another example, you can use FILENAME to attach information 
from external files, such as electronic mail files, as note files. To do 
this, you can write a definition file to process the external files, cre¬ 
ating a separate item for each external file. To attach an external file 
as the note file for an item, include FILENAME in @note_file. By 
specifying FILENAME as the external file name, you instruct 
TXT2STF to attach the current text file as a note file. 
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EOF 

EOF stands for end of file. You can use this variable to specify the 
termination point in an @item2 / ©note, @category_note, @make_exte- 
mal_note, or ©skip lines. 

CR 

CR stands for carriage return. You can use this variable whenever 
you want TXT2STF to use the combination of carriage return (ASCII 
decimal 13) and linefeed (ASCII decimal 10) as a value. 

For example, you can use the variable CR in an @append__note com¬ 
mand to specify where a new text line starts in the note text currently 
in the note buffer. When the note is imported into Agenda, the note 
text will break to a new line where the CR adds the carriage return 
and linefeed. 

CR is not affected by the TXT2STF /S command-line option. (See 
Chapter 6.) 

D, E, and W 

You can use these variables to represent Agenda-defined date catego¬ 
ries in definition file commands: 


Variable 

Means 


D 

Done date 


E 

Entry date 


W 

When date 



@append 


©append adds a string to the end of the contents of a specified vari¬ 
able. 

Syntax 

@append(”variable-mme",string) 

variable-name identifies the variable to which to append the string. 
variable-name is a variable name string constant. 
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string is the string to be appended, string is a string constant. You 
can specify the actual string value, in a pair of quotation marks (" ”), 
or the name of a variable that contains the string. 

Example 

The following sample command adds the text Company to the end of 
the variable tempvar: 


\ @append( 

"tempvar","Company") 

In this example, if tempvar contains the value One (the word One 
followed by a space) before ©append is executed, it contains the 
phrase One Company after this command. 

Changes made by this command 

Elements that commands can change 

Changes made by this command 

Current line in memory 

None 

Item, category, and note buffers 

None 

Variables 

Can create new variables or add to the 
contents of existing ones 

Location in text file 

None 

Structured file 

None 


@append_item 


@append_item adds a string to the end of the current contents of the 
item buffer. If TXT2STF is not currently constructing an item, this 
command also begins the item. 

Syntax 

@append_item(sfring[,N3) 

string is the string to be added to the end of the current item buffer. 
string is a string constant. You can specify an actual string value, in a 
pair of quotation marks (" "), or the name of a variable that contains 
the string. 

N (optional) prohibits TXT2STF from adding text to the note buffer if 
the item buffer becomes full. 
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Example 

This example shows one way to convert the following memo: 

To: Jill “ 

From: Linda 

Subject: Your proposal 

Jill, I liked your proposal 

but I had a few questions, 

could we get together next Wednesday 

to talk about it? 


The sample definition file shown below converts the names Jill and 
Linda into categories and converts the remaining memo text into an 
item. 

The definition file creates the item in two stages. First, it puts the 
subject text (Your proposal) into the item buffer and uses 
@append_item to add a space character ( ) to the end of the item 
buffer. 

Next it processes each line of the indented text. It executes @trim to 
remove the leading spaces from the text line and puts the remaining 
text into the variable called LINE. Then it executes 
©append Jtem to add the text in variable LINE to the item buffer, 
followed by another @append_item that adds a space character ( ) to 
the end of the item buffer. These changes eliminate the existing line 
breaks in the message. On import. Agenda wraps the item text to fit 
the item column width. 


#Converting memo text using @append_item 

START ©equate("SPACE", " ") 

©equate("PERSON","") 

©start () 

#Create To category ("To:" starts each memo in the file) 

' ,/v To\: " ©end () 

©trim("^To\:", N, "PERSON") 

@custom_category{PERSON, "To",) 

#Assign a person to the From category 

" A From\ :" @trim("''From\ :N, "PERSON") 

@custom__category (PERSON, "From", ) 


continued 
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#Add subject line to item buffer 

" A Subject\ :" @trim( ,,A ", "Sub ject\: ", ,) 

@itexn2 ("$") 

@ append_item(S PACE) 

#Discard blank lines so "~To\:"(NOT To:) won't match them 
" A [ )*$" @equate("blanks","") 

#Add each remaining line to item buffer 

" A ~To\:" @trim(" A : N, "LINE") 

@ append_item(LINE) 

@append_item(SPACE) 

END @end() 

When the resulting structured file is imported into Agenda, To and 
From are added as categories under the category specified when you 
use the Agenda File Transfer Import command. The name Jill is 
added as a child of To, and Linda is added as a child of From. The 
item, which consists of the text from the Subject line plus the four-line 
memo, is assigned to the categories Jill and Linda. 

To see what the structured file for this example looks like, see "A 
Simple Electronic Mail Example” in Appendix B. 

Changes made by this command 

Elements that commands can change Changes made by this command 
Current line in memory None 

Item, category, and note buffers Adds to the contents of the item buffer. If 
the item buffer becomes full, the rest of 
the string specified is added to the end of 
the note buffer, unless you specify other¬ 
wise. TXT2STF issues a warning when 
the item buffer becomes full. 

Variables None 

Location in text file None 

When the next @end is executed, the 
appended string is part of the item 
added to the structured file. 


Structured file 
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@append_note 


©appendjnote adds a string to the end of the current note, as stored 
in the note buffer. If TXT2STF is not currently constructing a note, 
this command also begins a note for the current item. 

Syntax 

@app endnote(s tring) 

string is the string to be added to the end of the note buffer, string is a 
string constant. You can specify an actual string value, in a pair of 
quotation marks (" ”), or the name of a variable that contains the 
string. 

Example 

This example shows one way to convert the following memo: 


To: Jill 
From: Linda 

Subject: Your proposal 

Jill, I liked your proposal 

but I had a few questions, 

could we get together next Wednesday 

to talk about it? 


The sample definition file shown below converts the names Jill and 
Linda into categories and converts the text on the Subject line into an 
item. Then it converts the remaining memo text into an item note. It 
executes ©trim to put the memo text into a variable (without the 
leading spaces) and executes @append_note to add the text to the 
note buffer, followed by an @append_note to add a space 
character ( ) to the end of the note buffer. These changes eliminate 
the existing line breaks in the message. On import. Agenda wraps the 
note text to fit the note screen. 
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fConverting memo text using @append_note 

START ©equate("SPACE"," ") 

©equate("PERSON","") 

©start() 

^Create To category ("To:" starts each memo in the file) 

" A To\:" @end() 

©trim(" A To\:", N, "PERSON") 

@custom_category(PERSON, "To",) 

#Assign a person to the From category 

" A From\:" @trim(" A From\:"$", N, "PERSON") 

@custom_category(PERSON, "From",) 

#Add subject line to item buffer 

"^Subject\:” ©trim(" A ","SubjectX:",,) 

@item2("$") 

fDiscard blank lines so "~To\:"(NOT To:) won't match them 

" A [ ]*$" ©equate ( "blanks","") 

#Add each remaining line to note buffer 

" A ~*To\:" @trim( ,,A : N, "LINE") 

@append_note(LINE) 

@append_note(SPACE) 

END ©end{) 


When the resulting structured file is imported into Agenda, To and 
From are added as categories under the category specified when you 
use the Agenda File Transfer Import command. The name Jill is 
added as a child of To and Linda is added as a child of From. The 
item, which consists of the text from the Subject line, is assigned to 
the categories Jill and Linda. The note, which consists of the body of 
the message, is added to the item. 
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©category 


Changes made by this command 


Elements that commands can change 

Changes made by this command 

Current line in memory 

None 

Item, category, and note buffers 

Adds to the contents of the note buffer. 

If the note buffer becomes full, the 
remaining portion of the string is 
ignored. TXT2STF issues a warning that 
the note buffer is full. 

Variables 

None 

Location in text file 

None 

Structured file 

When the next ©end is executed, the 
appended string is part of the note added 
to the structured file. 


@category creates one or more categories from the input text, and 
optionally makes them children of a specified parent category. The 
category is added as a child of the current category, as specified when 
you use the Agenda File Transfer Import command, unless you spec¬ 
ify that the parent category is a child of MAIN. 

If the specified category already exists. Agenda retains the existing 
category and does not create a duplicate category. If you specify a 
parent, the category created by ©category becomes its child when the 
structured file is imported into Agenda. If the specified parent does 
not already exist. Agenda creates it on import. 

The current item is assigned to this category. The item and category 
must both be created before an ©end copies the item and its catego¬ 
ries to the structured file. 

The item buffer can be empty when TXT2STF copies the category to 
the structured file. When you import the resulting structured file. 
Agenda adds the category to the category hierarchy but does not 
assign the any items to the category. 

Syntax 

©category {separator-pattern,[parent],[''type'']) 
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separator-pattern identifies the character or characters that TXT2STF 
uses to determine where a given value ends and the next value 
begins, separator-pattern is a pattern constant. This pattern can 
include the space character ( ). You can specify the pattern itself, in a 
pair of quotation marks (" "), or the name of the variable that contains 
the separator pattern. 

TXT2STF makes each value into a separate category. The categories 
do not include the characters that match the separator pattern. 

Tip Specifying the dollar sign ($) (the end-of-line character) as the 
separator pattern tells TXT2STF to make the entire text line a 
single category. 

parent (optional) is the parent of the new categories, parent is a string 
constant. You can specify the parent category name, in a pair of 
quotation marks (" "), or the name of a variable that contains the cate¬ 
gory name. 

You can specify the entire name of the parent category, including its 
parents. Use two backslashes (\\) to separate category names, with¬ 
out including any spaces. (A single backslash (\) is a special charac¬ 
ter that tells TXT2STF to use the next character as a regular character 
and not as a special character.) For example, to identify a parent 
category named Sales that is a child of Personnel in the category hier¬ 
archy, specify "Personnel\ \Sales". 

If a category name string begins with two backslashes (\\) the first 
category in the string is added as an immediate child of MAIN. 

type (optional) specifies the type of category to be created, type is a 
type constant. You can specify "date”, "exclusive", "numeric", "stan¬ 
dard", or "unindexed". If you omit type, TXT2STF uses "standard". If 
the category already exists and is a different type. Agenda retains the 
original category and type on import. 

Example 

This example shows how to convert the following text in order to 
import the memo recipient names as child categories under the par¬ 
ent category To, which is itself a child of People, and the company 
name under the parent category Company: 


To: Todd, Lynne, Sam, Julie 
Company: ABC Corporation 



Definition File Commands 5-21 


That is, it converts the above text so you can import the following 
category hierarchy, with People and Company both children of 
MAIN: 

People 

To 

Todd 

Lynne 

Sam 

Julie 

Company 

ABC Corporation 

The sample definition file converts the text file by first processing the 
To line and then the Company line. The statement that starts with 
the pattern " A To\:” processes the first text line, ©trim removes the 
string To:, which is the word To followed by a colon (:), from the line. 
Then ©category divides the remaining text line into separate values 
using a comma (,) or space character ( ), or a combination of the two 
(as specified by the pattern ]+"). Then ©category makes each of 
the resulting values into categories. 

To process the second text line, the definition file trims the string 
Company: from the line, ©category makes the rest of the current line 
a category under the parent category Company. 


♦Definition file that creates categories 
START @start () 

♦Convert names on "To" line into multiple categories 

" A To\: " @trim (" A ", "\: ", , ) 

Qcategory (" [, ] + ”, "WPeopleWTo", ) 

♦Convert Co. name on "Company" line into one category 

,,A Corapany\: " @trim(" A ", ) 

@category("$","\\Company",) 

END @end{) 


When the resulting structured file is imported into Agenda, the Peo¬ 
ple and Company categories are added as children of MAIN. 

See @custom_category for an example of using ©category to create a 
numeric category and for an example of using @custom_category to 
create a single category from a text line. 
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Changes made by this command 


Elements that commands can change 

Changes made by this command 

Current line in memory 

None 

Item, category, and note buffers 

Adds one or more categories to TXT2STF 
category buffers 

Variables 

None 

Location in text file 

None 

Structured file 

When the next ©end command is 
executed, TXT2STF copies a category 
definition for each category buffer 
created by ©category. 


@category_note 


@category_note creates a category note and assigns it to the most 
recently created category. The category and category note must both 
be created before an @end copies the category and its note to the 
structured file. 

Syntax 

@category_not e(termination-pattern) 

termination-pattern describes the string that ends the category note. 
termination-pattern is a pattern constant. You can specify the pattern 
itself, in a pair of quotation marks (" ”), or the name of a variable that 
contains the pattern. 

The note starts with the current text line and ends the note when it 
finds the specified termination pattern. The note does not include the 
line containing the termination pattern; that line is the next text line 
to be processed. 

Tip To use only the current text line as the note, specify caret ( A ) 
as the termination pattern. This causes TXT2STF to terminate 
the note when it reaches the start of the next text line. 
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Example 

This example shows how to convert a file that contains these lines 
and make the name Mia Fischer into a category, and the company 
name and address into a note for the category: 


Send To: Mia Fischer 

Toys Toys Toys Inc. 
1234 Pinkham Road 
Storyville, WA 02138 


The following sample definition file searches for the string Send To: 
at the start of a text line and trims the string from the line. Then, 
©category adds the name Mia Fischer as a child of the To category. 
@skip_lines then instructs TXT2STF to skip to the next line, which 
becomes the first line in a category note created by @category_note. 
The category note ends when TXT2STF finds a row of dashes in the 
text file. 


START @start() 

#Trim out "Send To:" and make rest of line a category 

" A Send To\:" @trim("^","\:",) 

@category"\\To",) 

#Skip to next line and make rest of text a category note 

@skip_lines(1) 

@category__note (" *-*") 

END @end() 


When the resulting structured file is imported, the To category is 
added as a child of MAIN. The note is added as its category note. 

Changes made by this command 


Elements that commands can change Changes made by this command 


Current line in memory The first line that contains the termina¬ 

tion pattern. 

Item, category, and note buffers The note created by this command is 

associated with the category most 
recently added to the category buffer. 

Variables None 


continued 
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Elements that commands can change Changes made by this command 

Location in text file The new location is the beginning of the 

first line from the old current line that 
matched the pattern termination-pattern. 

Structured file When the next @end is executed, a cate¬ 

gory note is defined in the structured file 
__for the category mentioned above. 


@category_note_f i le 


@category_note_file identifies the external note file for the current 
category. Agenda attaches the note to the most recently created cate¬ 
gory. The category and category note must both be created before an 
©end copies the category and its note to the structured file. 

Note If you include both ©categoryjnote_file and ©category note 
for a category, TXT2STF ignores the @category_note and 
copies only the name of the note file specified by ©cate- 
gory_note_file to the structured file. 

Note TXT2STF does not check whether the file exists. If the file 
does not exist. Agenda asks whether you want to create it 
when you ask to look at the note in the Agenda file. 

Syntax 

©category_noteJile(file-name) 

file-name is the note file name, file-name is a file name string constant. 
You can specify the name itself, in a pair of quotation marks (" "), or 
the name of a variable that contains the file name. 

Example 

This example creates a category called Quarter2 under the parent 
category Fiscal Year. It specifies the file QUARTER.DAT as a note file 
for that category. 


@custom_category("Quarter2","Fiscal Year",) 
@category_note_file("quarter.dat n ) 
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When the resulting structured file is imported, the Fiscal Year cate¬ 
gory is added as a child of the category specified when you use the 
Agenda File Transfer Import command. Quarter2 is added as a child 
of Fiscal Year. The note file QUARTER.DAT is attached as the cate¬ 
gory note for Quarter2. 


Changes made by this command 


Elements that commands can change 

Changes made by this command 

Current line in memory 

None 

Item, category, and note buffers 

The note for the last category defined is 
set to the file name specified. 

Variables 

None 

Location in text file 

None 

Structured file 

When the next ©end is executed, a cate¬ 
gory note is defined in the structured file 
for the category mentioned above. 


@custom_category 


@custom_category creates a category from text that you specify and 
optionally makes them children of a specified parent category. The 
category is added as a child of the current category, as specified when 
you use the Agenda File Transfer Import command, unless you spec¬ 
ify that the parent category is a child of MAIN. 

If the category already exists. Agenda retains the existing category 
and does not create a duplicate category. If you specify a parent, the 
category created by @custom_category becomes its child when the 
structured file is imported into Agenda. If the specified parent does 
not already exist. Agenda creates it on import. 

The current item is assigned to this category. The item and category 
must both be created before an ©end copies the item and its catego¬ 
ries to the structured file. 

The item buffer can be empty when TXT2STF copies the category to 
the structured file. When you import the resulting structured file. 
Agenda adds the category to the category hierarchy but does not 
assign any items to the category. 
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Syntax 

@custom_ca tegory (cat egory, [paren t ],[" type”]) 

category is the category name, category is a string constant. You can 
specify the category as a string, in a pair of quotation marks (" "), or 
the name of a variable that contains the string. 

parent (optional) is the parent category to which the new category is 
added, parent is a string constant. You can specify a parent category 
name, in a pair of quotation marks (""), or the name of a variable that 
contains a category name. 

You can specify the entire name of the parent category, including its 
parents. Use two backslashes (\\) to separate category names. (A 
single backslash (\) is a special character that tells TXT2STF to use the 
next character as a regular character and not as a special character.) 
For example, to identify a parent category named Sales that is a child 
of Personnel in the category hierarchy, specify "PersonnelWSales". 

If a category name string begins with two backslashes (\\) the first 
category in the string is added as an immediate child of MAIN. 

type (optional) specifies the type of category to create, type is a type 
constant. You can specify "date", "exclusive", "numeric", "standard", 
or "unindexed". If you omit type , TXT2STF uses "standard". If the 
category already exists and is a different type. Agenda retains the 
original category and type on import. 

Example 

This example shows one way to convert the following sample text 
lines to make ABC Corporation an item that is assigned to the cate¬ 
gory Lyle Clark and also is assigned to the numeric category named 
Company # with the number 5012. 

Company Number: 5012 
Company: ABC Corporation 
Contact: Lyle Clark 


The following sample definition file converts the above text file. The 
first statement is executed when TXT2STF finds the string Company 
Num at the start of a text line, ©skip deletes the start of the text line 
up through the colon(:). ©category makes the rest of the text line (the 
number 5012) a numeric value for the category Company #, which is 
a numeric category. 
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The next statement is executed when TXT2STF finds the string Com¬ 
pany: at the start of a text line, ©skip deletes the string Company: 
from the line. @item2 makes the remaining text line (ABC 
Corporation) into an item. 

The final statement is executed when TXT2STF finds the string Con¬ 
tact: at the start of a text line, ©trim puts the entire text line into the 
variable contact_var, after first removing the string Company:, 
through the colon (:), from the line. Then @custom_category adds the 
contents of contact_var (Lyle Clark) as a category under the parent 
category Contact. Since @custom_category omits the third argument, 
which specifies the type of category to create, the name ABC Corpo¬ 
ration is added as a standard category. 


START ©start() 


" A Company nuirT @skip{"\:" ; 

©category (' 

-1) 

"$","Company #","numeric") 

" A Company\:" ©skip ("\:”, 

@item2("$"] 

rl) 

" A Contact\:" @trim( ,,A .*\"contact var") 

@custom_category (contact var, ” WContact",) 

©end () 

When the resulting structured file is imported, the categories Contact 
and Company # are added as children of MAIN. Lyle Clark is added 
as a child of Contact. The item ABC Corporation is assigned to the 
category Lyle Clark and also assigned to the category Company # 
with the numeric value 5012. 

Changes made by this command 

Elements that commands can change 

Changes made by this command 

Current line in memory 

None 

Item, category, and note buffers 

Creates a new category 

Variables 

None 

Location in text file 

None 

Structured file 

When the next ©end is executed, the 
category created is added to the 
structured file. 
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©date 


©date lets you create assignments to date categories, ©date specifies 
the category name and optionally specifies a date value, such as 
11/12/90. The date category can be a category defined by Agenda 
(Entry, When, or Done) or any other date category you create. 

When ©end copies the category specified by ©date to the structured 
file, it also copies the item in the item buffer to the structured file. 
When the structured file is imported. Agenda uses the date value 
specified by ©date to assign the item to the date category. 

If the date category already exists. Agenda retains the existing cate¬ 
gory and does not create a duplicate category. 

Caution If there is no item in the item buffer when the next ©end is 
executed, then on import Agenda creates the category but 
does not import the date value since there is no item to 
assign to the date category. 

To assign the same date value to more than one date category, 
include a separate ©date for each date category. 

By default. Agenda assumes that the dates in the structured file are in 
the format MM/DD/YY. To specify a different format, use 
@date_format. 

Syntax 

©dat e(category[,value]) 

category is the name of the date category. This value must be a string 
constant. You can specify either the category name, in a pair of quo¬ 
tation marks (" ”), or a previously defined variable that contains the 
name of the category. 

value (optional) is the date value used in the assignment, for example 
11/12/90. This value must be a string constant. You can specify 
either the value itself, in a pair of quotation marks (" "), or a pre¬ 
viously defined variable that contains the date value. 

If you omit value, TXT2STF uses the entire current text line in the 
assignment. On import. Agenda discards any portion of the line that 
is not part of a valid date. 
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Example 

This sample locates a text line that starts with a date value in stan¬ 
dard MM/DD/YY format, and makes the date value a When date. 
The sample also creates an item from a text line that starts with the 
word What. 


*' A (:d:d/ :d:d/ :d:d) " @date(W) 

wA What" @item2("$") 

@end () 


When the resulting structured file is imported, the item created by 
the @item2 command is assigned to When. 

See @date_format for another example. 

Changes made by this command 


Elements that commands can change 

Changes made by this command 

Current line in memory 

None 

Item, category, and note buffers 

Adds a date category to TXT2STF 
category buffers 

Variables 

None 

Location in text file 

None 

Structured file 

When the next @end is executed, the date 
category is added to the structured file. 

If an item exists in the item buffer at that 
time, TXT2STF also adds the item to the 
structured file and assigns it to the date 
category using the value specified by the 
@date. Otherwise, there is no item to 
assign to the category, and so the cate¬ 
gory is imported into Agenda but the 
associated date value is ignored. 


@date_format 


@date_format describes the format of the dates and times in the struc¬ 
tured file. On import. Agenda uses this date format specification to 
interpret dates in the structured file. @date_format is particularly 
useful if you are likely to have dates in international date formats. 
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By default, Agenda assumes that the dates in the structured file are in 
the format MM/DD/YY and that times are specified using a 24-hour 
clock. Use @date_format if dates in the text file have a different for¬ 
mat. You can omit @date_format if all dates in the structured file are 
specified either in the default format (MM/DD/ YY) or in a 
combination of words and numbers, as in "Thursday November 8 
1990". 

You can use @date_format once at the beginning of the definition file 
if your text file contains dates in only one format. If the date format 
changes at intervals in your text file, include a new @date_format 
immediately before any commands in a statement that process dates in 
the new date format. 

TXT2STF copies the date format to the structured file when an @end 
is executed. If more than one @date_format is executed between a 
given @start/@end (or @end/@end) pair, only the last @date_format 
is used. 

Syntax 

@da.te_£ormat(format-number) 

format-number is a numeric constant that indicates the format of the 
dates in the text file. Use any of the following format numbers (for¬ 
mat 1 is the default): 


Format number 

Associated date format 

Associated time format 

1 

MM/DD/YY 

24-hour clock 

2 

DD/MM/YY 

24-hour clock 

3 

DD.MM.YY 

24-hour clock 

4 

YY-MM-DD 

24-hour clock 

5 

DD-MMM 

24-hour clock 

6 

DD-MMM-YY 

24-hour clock 

7 

MM/DD/YY 

12-hour clock 

8 

DD/MM/YY 

12-hour clock 

9 

DD.MM.YY 

12-hour clock 

10 

YY-MM-DD 

12-hour clock 

11 

DD-MMM 

12-hour clock 

12 

DD-MMM-YY 

12-hour clock 
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Note These are only a subset of the date formats supported by 

Agenda. (See Chapter 7 in the User's Guide.) For another way 
to convert dates into different formats, see ©replace. 

Example 

This example converts the dates in electronic mail messages when 
you get mail from mail nodes in both the United Kingdom (UK) and 
the United States (US). If the mail has the string "UK_Node" (which 
in this example identifies it as being from the UK), the date format is 
set to DD/MM/YY. If it has the string "US_Node" (which identifies it 
as being from the US), the date format is set to MM/DD/YY. 


" A via" 

@start () 

"UK_Node" 

@date_format (2) 

"USJSTode” 

@date_format (1) 

":d:d/:d:d/:d:d" 

@date(W) 

"Subject" 

@item2("$") 

@end() 

When the resulting structured file is imported, the item created by 
@item2 is assigned to the When date created by ©date. 

Changes made by this command 

Elements that commands > 

can change Changes made by this command 

Current line in memory 

None 

Item, category, and note buffers None 

Variables 

None 

Location in text file 

None 

Structured file 

When the next ©end is executed, 

TXT2STF copies the most recent date for¬ 
mat specification to the structured file, 
which tells Agenda the date format to 
use to interpret all subsequent dates in 
the structured file. 



5-32 Definition File Commands 


@end 


Copies the contents of TXT2STF item, category, and note buffers to 
the structured file as items, notes, and categories. @end then ini¬ 
tializes the buffers. 

An ©end must be executed for each item to be copied to the struc¬ 
tured file. You do not, however, need to include an ©end for items 
created by ©table because ©table internally executes an ©end (and 
©start) for each item it creates. 

©end also should be the last command executed in the definition file. 
There are two ways to ensure that ©end executes last: 

• Add a statement of the following form to the definition file: 

END @end() 

• Make ©end the last command in the statement that matches the 
last line of your text file. 

Caution If the definition file ends with a command other than 

©end, the structured file might not contain all the informa¬ 
tion it is supposed to. 

©end does not initialize the contents of variables. To initialize a vari¬ 
able you can use ©append, ©equate, ©grab, ©set, and ©trim. 

Syntax 

@end() 

©end has no arguments, but the parentheses are required. 

Example 

This sample statement copies the accumulated information to a struc¬ 
tured file when it finds the word Sincerely followed by a comma (,) at 
the end of a text line. 


"Sincerely,$" 


@end() 
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Changes made by this command 

Elements that commands can change Cha nges made by this command 
Current line in memory None 

Item, category, and note buffers Clears these buffers after writing them to 
the structured file 

Variables None 

Location in text file None 

Structured file Copies the contents of item, note, and 

_category buffers to the structured file 


©equate 


©equate initializes a variable and then puts the specified string in the 
variable. If the variable already exists, the information it contained 
before ©equate is lost. 

©equate is a convenient way to initialize variables. You also can use 
it to associate the variable name with a pattern or text string. After 
you use ©equate, you can specify the variable name in other com¬ 
mands instead of the pattern or text string. 

Syntax 

©equat e(”variable-mme"" string") 

variable-name is the variable into which the string is placed, variable- 
name is a variable name string constant. 

string is the pattern or string constant, enclosed in a pair of quotation 
marks C "), or a previously defined variable that contains a string or 
pattern constant. 

Example 

In this example, ©equate associates the variable with the string Com¬ 
pany. Then, on any line that starts Company: or any other string that 
begins with the string Co and ends with a colon (:), TXT2STF puts 
everything after the colon (:) into the variable Category. @custom_ca- 
tegory then uses both variables Category and Parent to create a cate¬ 
gory. 
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@start() 

Qequate ("Parent", "WCompany") 

@trim( HA Co.*\:", N, "Category") 

@custom__category (Category, Parent,) 
@end() 


When the resulting structured file is imported into Agenda, the Com¬ 
pany category is added as a child of MAIN. 

Changes made by this command 


Elements that commands can change 

Changes made by this command 

Current line in memory 

None 

Item, category, and note buffers 

None 

Variables 

Creates new variables or replaces the 
contents of existing ones 

Location in text file 

None 

Structured file 

None 


@grab 


©grab temporarily divides portions of the current text line into values 
and puts one or more of the resulting values into variables. If a vari¬ 
able already exists, its previous contents are lost. If a variable does 
not exist, TXT2STF creates it. 

©grab leaves the text line intact in memory. The next command in 
the statement can operate on the same text line that ©grab originally 
processed. All commands that follow ©grab can use values that 
©grab stores in variables. 

To put text into variables, ©grab first divides the line into values 
using the specified separator pattern. It then assigns a number to 
each value, assigning the number 1 (one) to the first (leftmost) value, 
the number 2 to the second, and so forth. Finally, ©grab puts into 
variables the values you identify by number. For example, to put the 
second value from the text line in a variable, you tell ©grab to put 
value number 2 in a specific variable. 


START 

" A Co. * \ " 
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Syntax 

@grab(separator-pattem,]position-number"variable-name” 

[,position-number, "variable-name",...]) 

separator-pattern describes the string that TXT2STF uses to divide the 
line into separate values. This pattern specifies where a given value 
ends and another begins, separator-pattern must be a pattern constant. 
You can specify the actual string/ in a pair of quotation marks (" "), or 
a variable that contains the string value. 

position-number identifies, by number, the value to put in a variable. 
position-number must be a numeric constant. For each position num¬ 
ber, you must also identify a variable. 

variable-name identifies the variable in which to put the value identi¬ 
fied by position-number, variable is a variable name constant. 

To identify more than one value in a single ©grab, specify a position- 
number and variable for each value. The position number and variable 
pairs must all be on the same line as the rest of the ©grab command. 
Put a comma (,) before each new position number. If you identify a 
value that does not exist, TXT2STF ignores the position number and 
its associated variable, and continues executing the command. For 
example, if you specify a variable for the fifth value, and only four 
values exist, TXT2STF does not change the specified variable. 
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Example 

This example shows one way to convert the following text, by mak¬ 
ing make the first word on the line, such as To or From, into a parent 
category, and the name on the line into its child category. 

To: Mark 

From: Sonjaya 

Company: ABC Corporation 


That is, you import the following category hierarchy: 

To 

Mark 

From 

Sonjaya 

Company 

ABC Corporation 

The following sample definition file processes one text line at a time. 
The pattern matches each line that starts with a string fol¬ 

lowed by a colon (:). After the line is matched, ©grab puts the first 
string on the text line, such as To, in a variable called Parent and puts 
the second string after the colon (:) in a variable called Category. For 
each line, @custom_category creates a category using the text current 
in the Category variable, and whose parent is the text stored in the 
Parent variable. 


START @start () 

: " @grab("\ : ", 1 , "Parent", 2, "Category") 

@custom_category(Category,Parent,) 

END @end() 


When the resulting structured file is imported, categories To, From, 
and Company are added as children of the category you specify 
when you use the Agenda File Transfer Import command. 
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Changes made by this command 


Elements that commands can change 

Changes made by this command 

Current line in memory 

None 

Item, category, and note buffers 

None 

Variables 

Creates new variables or replaces the 
contents of existing ones 

Location in text file 

None 

Structured file 

None 


@item 


©item creates an item using text from the text file. The item starts 
with the current text line and can include subsequent text lines from 
the text file, depending on the arguments you specify in the com¬ 
mand. 

Note ©item is an alternative to @item2. If you already have defini¬ 
tion files that use ©item, you can continue to use them. How¬ 
ever, to have more control over how TXT2STF constructs 
items, consider using @item2 and not ©item in your definition 
files. (See "@item2" later in this chapter.) 

The item created by ©item includes the entire current text line. (If 
you want to remove characters from this text line, use trimming com¬ 
mands before executing ©item.) ©item adds additional text lines to 
the item buffer until it either finds the termination pattern for the 
item or the item buffer contains the maximum number of characters, 
as specified in the ©item command. (This differs from @item2, which 
copies text only up to where the termination pattern or maximum 
length is encountered, even if this means stopping in the middle of 
the first text line.) 

TXT2STF maintains a single item buffer. This means you can create 
only one item at a time. If more than one ©item is executed between 
the ©start (or ©end) that initializes the buffer and the ©end that 
copies the item buffer to the structured file, TXT2STF adds the text to 
the end of the item and/or note buffer, as appropriate. 
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The item buffer can contain up to 350 characters. If this buffer fills 
during execution of ©item, TXT2STF puts the remaining characters in 
the current note buffer, unless you specify otherwise in ©item. The 
TXT2STF note buffer can contain up to 10,000 characters, ©item stops 
copying text to the note buffer when it encounters the termination 
pattern in a text line, fills the note buffer, or reaches the end of the 
text file. 

For each text line that it processes, ©item always uses the entire text 
line. It does not process portions of a text line. (This differs from 
@item2, which processes each text line character by character.) 

©item always copies the entire first text line it processes to the item 
buffer. Then TXT2STF loads the next unprocessed text line into 
memory. At this time, ©item starts searching for the termination 
pattern or testing to see if the maximum number of characters have 
been added to the item. TXT2STF goes through line after line of text, 
adding each one to the item (or note) buffer, until either the termina¬ 
tion string or maximum number of characters is encountered. When 
either of these occurrences ends ©item, TXT2STF loads the next 
unprocessed text line into memory, and continues processing the text 
file. (This is different from @item2, which can copy a portion of the 
current text line to the item buffer, which means that the next com¬ 
mand in the current statement starts where @item2 stopped process¬ 
ing the current text line. See "@item2" later in this chapter.) 

Syntax 

@item( terra ination-pa item, total-length ,[N]) 

termination-pattern describes the string that ends the item text. 
termination-pattern is a pattern constant. The pattern can consist of 
one or more characters, including the space character ( ). You can 
specify the pattern itself, in a pair of quotation marks (" "), or the 
name of a variable that contains the pattern. 

Tip To use only the current text line as the item, specify caret ( A ), 
which is the start-of-line character, as the termination pattern. 
This causes TXT2STF to terminate the item when it reaches 
the start of the next text line. 

©item starts searching for the termination pattern after copying the 
first text line to the item buffer. The line that contains the termination 
pattern is not included in the item. If ©item does not specify a total 
length, ©item stops executing when it the termination pattern is 
matched. Otherwise, ©item continues until either it copies the num¬ 
ber of characters specified by total-length into the item (or note) buffer 
or reaches the end of the text file. 
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total-length is a numeric constant that specifies the maximum number 
of characters ©item can process, total-length is a numeric constant. 
You can specify up to 350 for this value. 

©item adds the entire current text line to the buffer when any charac¬ 
ter in the line causes the item buffer to contain the maximum number 
of characters specified by total-length, even if this adds more than the 
specified number of characters. If ©item allows text to be added to 
the note buffer (specified by N, below) and the termination pattern 
has not yet been encountered, ©item adds text to the note buffer until 
it finds the termination pattern. The line that contains the termina¬ 
tion pattern is not included in the note. 

N (optional) prohibits TXT2STF from adding text to the note if the 
item buffer becomes full. 

Example 

This example shows one way to convert the following text into an 
item and item note: 


Re: Lunch 

Can't make lunch appointment today, can we reschedule for next week? 


The following sample definition file statement executes when 
TXT2STF finds the string Re: at the start of a line. @custom_category 
creates a category called Messages, ©skip causes TXT2STF to skip 
over the string Re: on the current line, and ©item makes Lunch an 
item, by including everything up to the start of the next line, as speci¬ 
fied by the pattern " A ". (The 80 supplements the " A ” specification, 
telling ©item that the item can be no longer than 80 characters in 
length.) ©note creates a note from the remaining text in the file, up to 
the end of the text file, as specified by the predefined variable EOF, or 
it fills the note buffer. 


" A Re\:" @start{) 

@custom_category("Messages”,,) 
@skip(" : +",1) 

@item{ ,,A,, , 80 ,) 

@note(EOF) 

Send() 


When the resulting structured file is imported into Agenda, Messages 
is added as a child of the category specified when you use the 
Agenda File Transfer Import command. The item created by ©item 
is assigned to the Messages category. The note is added as an item 
note. 
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Note As an alternative to @item(" A ",80,) and ©note(EOF), you 

could use the single command @item(EOF,80,), which makes 
an item from the current line (which internally is assumed to 
by 80 characters long) and then puts the remaining text lines 
into a note for the item. 


Changes made by this command 


Elements that commands can change 

Changes made by this command 

Current line in memory 

The text line that matched the termina¬ 
tion string, or the text line after the text 
line that caused the maximum number of 
characters to be added to the item (or 
note) buffer. 

Item, category, and note buffers 

Appends text to the item buffer and may 
append text to the note buffer. 

Variables 

None 

Location in text file 

Advances to the line where the item 
ends, or to the next line if the item con¬ 
tains only one text line. 

Structured file 

When the next @end is executed, an item 
is defined in the structured file using the 
contents of the item buffer. Text 
appended to the note buffer by ©item is 
added as an item note. 


@item2 


@item2 creates an item using text from the text file. The item starts at 
the beginning of the current text line and can include as many charac¬ 
ters from the current text line as necessary. The item also can include 
subsequent text lines from the text file, depending on the arguments 
you specify in the command. 

Note @item2 is an alternative to ©item, and provides greater flexi¬ 
bility in how you can create an item. 

The item created by @item2 starts at the beginning of the current text 
line, and continues until either it finds the termination pattern for the 
item or the item buffer contains the maximum number of characters, 
as specified in the ©item command. (This differs from ©item, which 
copies the entire first text line into the item buffer before it starts 
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looking for the termination pattern or checking to see if the item 
buffer is full. @item2 differs also in that it copies text into the item 
buffer character by character, and not line by line in the way ©item 
does.) 

TXT2STF maintains a single item buffer. This means you can create 
only one item at a time. If more than one @item2 is executed between 
the ©start (or ©end) that initializes the buffer and the ©end that 
' copies the item buffer to the structured file, TXT2STF adds the text to 
the end of the item and/or note buffer, as appropriate. 

The item buffer can contain up to 350 characters. If this buffer fills 
during execution of @item2, TXT2STF puts the remaining characters 
in the current note buffer, unless you specify otherwise in ©item. The 
TXT2STF note buffer can contain up to 10,000 characters. @item2 
stops copying text to the note buffer when it encounters the termina¬ 
tion pattern in a text line, fills the note buffer, or reaches the end of 
the text file. 

@item2 copies text to the item buffer character by character. The next 
command in the current statement starts where @item2 stopped pro¬ 
cessing the current text line. (This differs from ©item, which always 
copies entire lines of text into the item buffer. See "©item" earlier in 
this chapter for more information.) 

If @item2 is the last command in the statement, TXT2STF recopies the 
most recently processed text line back into memory, which means 
that the next text line to be processed is the same text line where the 
item ended. 

Syntax 

@item2(termimtion-pattern [, total-length] [,N]) 
or 

@item2(item-length[,N)) 

termination-pattern describes the string that ends the item text. 
termination-pattern is a pattern constant. The pattern can consist of 
one or more characters, including the space character ( ). You can 
specify the pattern itself, in a pair of quotation marks (” ”), or the 
name of a variable that contains the pattern. 

Tip To use only the current text line as the item, specify a dollar 
sign ($) as the termination pattern. This causes TXT2STF to 
terminate the item when it reaches the end of the current line. 
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@item2 includes in the item buffer characters up to, but not including, 
the matched characters. If @item2 does not specify a total length for 
an item, @item2 stops executing when it matches the termination pat¬ 
tern. Otherwise, @item2 continues until either it copies the maximum 
number of characters to the item (or note) buffer or reaches the end of 
the text file. 

total-length (optional) is a numeric constant that specifies the maxi¬ 
mum number of characters @item2 can process, total-length is a 
numeric constant. You can specify up to 350 for this value. 

@item2 stops adding characters to the item buffer when the item 
buffer contains the maximum number of characters. If @item2 allows 
text to be added to the note buffer (specified by N, below) and the 
termination pattern has not yet been encountered, @item2 adds text 
to the note buffer until it finds the termination pattern. The termina¬ 
tion pattern is not included in the note. 

item-length is a numeric constant that specifies the maximum number 
of characters the item can contain. TXT2STF stops adding characters 
to the item buffer when it contains the maximum number of charac¬ 
ters. item-length is a numeric constant. When the item buffer con¬ 
tains this number of characters, TXT2STF stops executing @item2. 

You can specify up to 350 for this value. 

N (optional) prohibits TXT2STF from adding text to the note if the 
item buffer becomes full. 

Example 

This example shows one way to convert the following text into an 
item and item note: 


Re: Lunch 

Can't make lunch appointment today, can we reschedule for next week? 


The following sample definition file statement executes when 
TXT2STF finds the string Re: at the start of a line. @custom_category 
creates a category called Messages, ©skip causes TXT2STF to skip 
over the string Re: on the current line, and @item2 makes an item 
from the current line (Lunch). Then ©note copies the remaining char¬ 
acters in the text file to the note buffer, until it reaches the end of the 
text file, as specified by the predefined variable EOF, or it fills the 
note buffer. 
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" A Re\:" @start() 

@custom_category("Messages”,,) 
@skip{": + ",1) 

@item2("$”) 

@note(EOF) 

@end() 


When the resulting structured file is imported into Agenda, Messages 
is added as a child of the category specified when you use the 
Agenda File Transfer Import command. The item created by @item2 
is assigned to the Messages category. The note is added as an item 
note. 

Note As an alternative to @item20'$") and @note(EOF), you could 
use the single command @item2(EOF,80), which makes an 
item from everything in the current line (up to a maximum of 
80 characters) and then puts the remaining text up to the end 
of the file into a note. 


Changes made by this command 


Elements that commands can change Changes made by this command 


Current line in memory The current line becomes the line where 

the item text ends. 

Item, category, and note buffers Appends text to the item buffer and may 
append text to the note buffer. 

Variables None 

Location in text file Advances to the next character after the 

item text. 

Structured file When the next ©end is executed, the 

item is added in the structured file using 
the contents of the item buffer. Text 
appended to the note buffer by @item2 is 
added as an item note. 


@make_external_note 


@make_external_note creates an external note file and copies text 
from the text file to the note file. The note file is associated with the 
item in the item buffer. 
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If the item buffer is empty when TXT2STF copies the external note 
file name to the structured file, the note file is not attached to an item 
when the structured file is imported to Agenda. This occurs when 
there are no item commands between the previous command that 
cleared TXT2STF buffers (©start or ©end) and the ©end that copies 
the note to the structured file. When you import the resulting struc¬ 
tured file. Agenda creates an empty item for the note. 

TXT2STF gives the note file a name of the form NOTEw.AGN, where 
n is a number between 1 and 9999. TXT2STF increments n by 1 each 
time it creates a note file. If a file already exists with this name, 
TXT2STF retains the existing file and increments n until it creates a 
unique file name. TXT2STF stores the file in the directory you spec¬ 
ify , and copies the name of the note file to the structured file. 

If an error occurs when TXT2STF tries to create the note file, for 
example the specified directory does not exist or TXT2STF cannot 
create the file for another reason, TXT2STF reports the error, ignores 
the command, and continues converting the text file. 

Syntax 

@make_extemal_note(termination-pattern,["directory"\) 

termination-pattern describes the string that ends the note text. 
termination-pattern is a pattern constant. You can specify the pattern 
itself, in a pair of quotation marks (”"), or the name of a variable that 
contains the pattern. 

TXT2STF starts the note with the current text line. After adding that 
text line to the external note file, TXT2STF starts searching for the 
specified termination pattern, and ends the note when it reaches a 
line that contains that pattern. The note does not include the line 
containing the termination pattern; that text line is the next line to be 
processed. 

directory (optional) is the name of the directory in which you want the 
note file to be stored, directory is a file name string constant. This 
value is a string constant. You can specify the directory name itself, 
in a pair of quotation marks (" "), or a predefined variable that con¬ 
tains the directory name. 

To store the note in the current directory, omit the directory argument. 
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Example 

The following sample statement is executed when TXT2STF finds the 
string Subject: at the start of a text line, ©skip removes Subject: from 
the text line. @item2 makes an item from the remaining text on the 
current line. @make_external_note copies all remaining text lines, up 
to the end of the text file (as specified by the predefined variable 
EOF) into a new note file called NOTEn.AGN (where n is the next 
available number) in the Agenda directory (\AGENDA). 


,,A Subject\: " @skip(" +",1) 

@item2("$") 

@make_external_note(EOF,"\agenda") 

When the resulting structured file is imported into Agenda, the note 
file is attached to the item created by @item2. 

Changes made by this command 

Elements that commands can change 

Changes made by this command 

Current line in memory 

The current line becomes the first line 
from the old current line that has a string 
which matches the termination-pattern. 

Item, category, and note buffers 

Causes TXT2STF to ignore the contents 
of the note buffer. 

Variables 

None 

Location in text file 

The next command begins executing on 
the beginning of the new current line. 

Structured file 

When the next ©end is executed, instead 
of writing the contents of the note buffer 
to the structured file, TXT2STF copies the 
name of the file note created by ©make- 
_external_note. 


@note 


©note creates a note and assigns it to the item in the item buffer. If 
TXT2STF finds more ©note commands before ©end copies the item 
and note to the structured file, TXT2STF appends the text to the exis¬ 
ting note. 
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To attach a note file, use @note_file instead of ©note. To assign the 
note to a category, use @category_note or @category_note_file. 

Caution ©note can only create notes that contain up to 10,000 char¬ 
acters (about seven pages of double spaced text). If the 
text contains more than this number of characters, use 
@make_external_note, which puts any number of charac¬ 
ters in a text file and attaches the text file as an external 
note. 

If the item buffer is empty when TXT2STF copies the note to the 
structured file, the note will not be assigned to an item when the 
structured file is imported to Agenda. This occurs when there are no 
item commands between the previous command that cleared 
TXT2STF buffers (©start or ©end) and the ©end that copies the note 
to the structured file. When you import the resulting structured file, 
Agenda creates an empty item for the note. 

Syntax 

©note (term ina tion-pattern) 

termination-pattern describes the string that ends the note text. 
termination-pattern is a pattern constant. You can specify the pattern 
itself, in a pair of quotation marks (""), or the name of a variable that 
contains the pattern. 

TXT2STF starts the note with the current text line. After adding that 
text line to the note buffer, TXT2STF starts searching for the specified 
termination pattern, and ends the note when it reaches a line that 
contains that pattern. The note does not include the line containing 
the termination pattern; that text line is the next line to be processed. 

Tip To use only the current text line as the note, specify caret ( A ) 

as the termination pattern. This causes TXT2STF to terminate 
the note when it reaches the start of the next text line. 
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Example 

The following sample definition file creates an item from text on a 
line starting with the string QUOTE, and a category from the text on 
a line starting with the string PUT. When TXT2STF finds the string 
DETAILS at the start of a text line, it starts a note for the current item. 
The note goes up to, but does not include, the next line that starts 
with the string QUOTE. 


" A Start_trans\:" @start () 


,,A QUOTE " ©skip (" +'\1) 

@custom_category ("Quotes", "WBuys",) 
@item2{"$") 

" A PUT " @ski.p (" +",1) 

©category("$","\\Buys\\Puts",) 

" A DETAILS " ©note(" A QUOTE ") 

©end() 


When the resulting structured file is imported into Agenda, Buys is 
added as a children of MAIN. Quotes and Puts are children of Buys. 
The category created by ©category is added as a child of Puts. The 
item created by @item2 is assigned to the Quotes category and to the 
category created as a child of Puts. 

Changes made by this command 


Elements that commands can change Changes made by this command 


Current line in memory The current line becomes the first line 

after the old current line that has a string 
that matches the termination-pattern. 


Item, category, and note buffers Appends into the note buffer all the 

information in the text file staring from 
the current location in the text file to the 
end of the line before the new current 
line. 

Variables None 

Location in text file The next command begins executing on 

the beginning of the new current line. 

Structured file When the next @cnd is executed, a note 

is defined in the structured file with the 

contents of the note buffer. 
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@note_file 


@note_file identifies the external note file for the item in the item 
buffer. 

Notes If you use both @note_file and ©note, TXT2STF ignores ©note 
and copies only the name of the note file specified by @no- 
tejftle to the structured file. 

TXT2STF does not check to see if the file exists. If the file does 
not exist. Agenda asks whether you want to create it when 
you try look at the note in the Agenda file. 

Syntax 

@note_fi\e(file-name) 

file-name is the name of the external note file, file-name is a file name 
string constant. You can specify the note file name itself, in a pair of 
quotation marks (" "), or the name of a variable that contains the note 
file name. 

Example 

The following sample definition file statement is executed when 
TXT2STF finds a line that starts with NEW VENDOR. @item2 creates 
an item from the current text line, ©notejile makes the current text 
file the note file for the item. (FILENAME is a predefined variable 
that represents the name of the current text file.) 


” A NEW VENDOR" @item2("$") 

@note_f ile (FILENAME) 


When the resulting structured file is imported into Agenda, the origi¬ 
nal text file is attached as a note file to the item created by @item2. 
Since TXT2STF does not change the text file when it converts text in 
it, the contents of the original file are available as note text. 




Definition File Commands 5-49 


©numeric 


Changes made by this command 


Elements that commands can change 

Changes made by this command 

Current line in memory 

None 

Item, category, and note buffers 

Causes TXT2STF to ignore the contents 
of the note buffer. 

Variables 

None 

Location in text file 

None 

Structured file 

When the next ©end is executed, instead 
of writing the contents of the note buffer 
to the structured file, TXT2STF defines a 
file note whose name is file-name. 


©numeric lets you create assignments to numeric categories, ©nu¬ 
meric specifies the category name and optionally specifies a numeric 
value. 

When ©end copies the category specified by ©numeric to the struc¬ 
tured file, it also copies the item in the item buffer to the structured 
file. When the structured file is imported. Agenda uses the numeric 
value specified by ©numeric to assign the item to the numeric cate¬ 
gory. 

If the numeric category already exists. Agenda retains the existing 
category and does not create a duplicate category. 

Caution If there is no item in the item buffer when the next ©end is 
executed, then on import Agenda creates the category but 
does not import the number since there is no item to 
assign to the numeric category. 

Syntax 

@numehc(category[ r value]) 

category is the name of the numeric category. This value must be a 
string constant. You can specify either the category name itself, in a 
pair of quotation marks (" ”), or a previously defined variable that 
contains the category name. 
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value (optional) is the numeric value used in the assignment. This 
value must be a string constant. You can specify either the value 
itself, in a pair of quotation marks (" "), or a previously defined vari¬ 
able that contains the value. 

If you omit value, TXT2STF uses the entire current text line in the 
assignment. Agenda imports the text line starting from the first char¬ 
acter on the line and continuing until it finds a nonnumeric character. 
Agenda ignores the rest of the line. If the first character is 
nonnumeric. Agenda ignores the entire line. 

Example 

The following sample command assigns the current item to the Cost 
category with a numeric value of 350.23. 


\ ©numeric ( "Cost ", "350.23") 

When the resulting text file is imported into Agenda, the numeric 
category Cost is imported as a child of the current category, as 
specified when you use the Agenda File Transfer Import command. 

Changes made by this command 

Elements that commands can change 

Changes made by this command 

Current line in memory 

None 

Item, category, and note buffers 

Adds a numeric category to TXT2STF 
category buffers. 

Variables 

None 

Location in text file 

None 

Structured file 

When the next ©end is executed, the 
numeric category is added to the struc¬ 
tured file. 


If an item exists in the item buffer at that 
time, TXT2STF also adds the item to the 
structured file and assigns it to the 
numeric category using the value speci¬ 
fied by ©numeric. Otherwise, there is no 
item to assign to the category, and so the 
category is imported into Agenda but the 
associated numeric value is ignored. 
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©replace 


©replace replaces the specified number of occurrences of a given 
string in the text line with another string. 

Syntax 

@replsLce(search-pattern,replacement-string,[number]) 

search-pattern describes the string for which TXT2STF searches. 
search-pattern is a pattern constant. You can specify the pattern itself, 
in a pair of quotation marks (” "), or a variable that contains the pat¬ 
tern. 

replacement-string is the string that replaces the string identified by 
search-pattern. This value must be a string constant. You can specify 
the string itself, in a pair of quotation marks (" "), or a variable that 
contains the string. 

number (optional) specifies the number of occurrences of search-pat¬ 
tern to be replaced by replacement-string, number must be a numeric 
constant. If you omit number in the text line, ©replace substitutes 
replacement-string for all occurrences of search-pattern in the text line. 

Example 

The following sample statement replaces all dashes in a text line with 
slashes. With the text line "11-12-90", you will get a When date of 
"11/12/90", which is in the Agenda default date format. 


":d:d-:d:d-:d:d" @replace ,) 

@date(W) 


See @date_format for other ways to transform dates into other for¬ 
mats. 

Changes made by this command 


Elements that commands can change 

Changes made by this command 

Current line in memory 

May alter the contents of the current line 

Item, category, and note buffers 

None 

Variables 

None 

Location in text file 

None 

Structured file 

None 
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©reset 


©reset replaces the text line in memory with the contents of the speci¬ 
fied variable, or with the text string you specify. 

You can use ©reset if you need to convert the same text line in more 
than one way or to use text from one text line when converting a later 
text line. To do this, save the complete or trimmed text line with the 
©set variable. Restore the saved line at a later time by using ©reset, 
and use the variable named in the ©set. 

Syntax 

@reset(replacement-string) 

replacement-string is the string that replaces the current text line in 
memory, replacement-string must be a string constant. You can spec¬ 
ify the string itself, in a pair of quotation marks (" "), or a variable that 
contains the replacement string. 

Example 

This example shows one way to convert information from the Lotus 
Metro® appointment book, extracting each appointment as an item. 
This example uses the following appointment book information, 
which has already been printed to an ASCII text file: 
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Monday, November 5,1990 
Book: MAIN 
6:00a 
7:00 

8:00 R.Ball (Shelley) 

9:00 

10:00 Meeting with Phil and Anne re. sign 

11:00 

12:00p 

1:00 to 3 - Downtown, Bookseller mtg. 


Tuesday, November 6,1990 
Book: MAIN 
6:00a 
7:00 
8:00 
9:00 

10:00 At Large Wkly Wrap-up 

11:00 

12:00p 

1:00 send-off plan review mtg. 


The following sample definition file uses variable Full Date to assign 
each item the correct When date and variable Book to assign each 
item to a category that names the book the item is from. 

Notice in this example that ©set specifies variable names, such as 
Date and Bookname, in a pair of quotation marks (" ") because it is 
simply naming the variables, ©reset names the Full Date variable 
without quotation marks to instruct TXT2STF to use the contents of 
the variable. 
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#Start collecting information for a new item, delete day name 
#<fcr example, Monday) from day header line, and put date 
#in variable Date 


" A :a -r, :a+ :d+, :d:d:d:d" @start() 

@trim(” A ", ) 
@set{"Date") 

#Put name of the book into variable Bookname 


,,A Rook\:" 

#Make contents of Bookname 


@skip(" ",) 

@set("Bookname") 
a child of category Book 


":d+\::d:d[ap l.*:a+" @custom_category(Bookname,"Book",) 

#Trim text, construct date and time in variable Full Date 


etrim(" A ", ” :df-\: :d:d", ,"Time") 
@trim( MA ",":n",N) 

@item2("$") 

@eq(uate ("Full Date", Date) 
@append("Full Date"," at ") 
@append("Full Date",Time) 


#Reset current line to contents of variable Full Date, 
#create a When date using the "new" line, and copy 
#current item/category/date info to structured file 


@reset(Full Date) 
@date(W) 

@end() 


When TXT2STF uses this definition file to convert the sample Metro 
file using the sample definition file, it creates five items for your 
Agenda file, one for each appointment listed in the file. 

Changes made by this command 


Elements that commands can change 

Changes made by this command 

Current line in memory 

Replaces the current line 

Item, category, and note buffers 

None 

Variables 

None 

Location in text file 

None 

Structured file 

None 
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@set 


@set stores the current text line in the specified variable. 

This lets you use the current text line in more than one way. You can 
save the text line by using @set, and then trim or convert the line 
however you want. Then, to use the original text line in another way, 
use ©reset to restore the full text line. The ©reset can be in a different 
statement than ©set. 

Tip ©set stores the entire text line in a variable. To save a portion 
of the line, use one of the trimming commands to remove 
unwanted text before you use ©set. 

Syntax 

@s et("variable-name") 

variable-name is the variable in which the text line is stored, variable- 
name must be a variable name string constant. 

See ©reset for an example of using ©set. 

Changes made by this command 


Elements that commands can change 

Changes made by this command 

Current line in memory 

None 

Item, category, and note buffers 

None 

Variables 

Copies the contents of the current text 
line to the specified variable 

Location in text file 

None 

Structured file 

None 


@skip 


©skip divides the current text line into separate values using the sep¬ 
arator pattern you specify. It then deletes the specified value from 
the text line. 
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This lets you remove unwanted text from the text line before you 
convert the line into an item, category, or note. TXT2STF uses the 
entire text line minus the unwanted text, leaving no spaces where the 
text was deleted. 

Tip If you want to use a text line in several ways, consider using 
©trim and not ©skip (since ©trim saves deleted text in vari¬ 
ables for later use). If you use ©skip, you can use ©set to save 
the original line in a variable before executing ©skip. To 
restore the original line at a later time, use ©reset. 

To delete text, ©skip first divides the line into values using the speci¬ 
fied separator pattern. It then assigns a number to each value, assign¬ 
ing the number 1 (one) to the first (leftmost) value, the number 2 to 
the second, and so forth. Finally, ©skip deletes the value whose 
number you identify in ©skip. For example, you delete the second 
value from the text line by telling ©skip to delete value number 2. 

Each ©skip removes one value from the text line. To remove more 
than one value from a line, you must include more than one ©skip in 
a statement. Each ©skip divides the line and renumbers the resulting 
values based on the specified separator pattern. 

Syntax 

@skip(sepa rator-pa ttern,posi tion-num ber) 

separator-pattern describes the string that TXT2STF uses to separate 
the text line into separate values. This pattern specifies where a given 
value ends and another begins. The separator pattern is included at 
the end of each string where it is found, separator-pattern must be a 
pattern constant. You can specify the pattern itself, in a pair of quota¬ 
tion marks (" "), or a variable that contains the pattern. 

position-number identifies, by number, the value to delete, position- 
number must be a numeric constant. 

Example 

This example shows one way to convert the following text line to 
create a category swind.pkyn, with a parent of ID. 

SYSID:swind:USERID:pkyn " “ 


The sample statement shown below is executed when TXT2STF finds 
the string SYSID: at the start of a text line. The first ©skip uses the 
colon (:), as specified by the pattern to separate the text line into 
four values (SYSID:, swind:, USERID:, and pkyn). The same ©skip 
then deletes the first value (SYSID:) from the text line. 
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The second ©skip again uses the colon (:) to separate the text line, 
which results in three values (swind:, USERID:, and pkyn). The same 
©skip then deletes the second value (USERID:) from the text line. 
Then ©category makes a category from the current text line, which 
now contains only swind:pkyn. 


" A SYSID\:" 

@skip 

pi) 


@skip{"\:", 

, 2 ) 


@category(' 

’ $ M ,”ID M ,) 


Changes made by this command 


Elements that commands can change 

Changes made by this command 

Current line in memory 

May delete text from the start of the 
current line 

Item, category, and note buffers 

None 

Variables 

None 

Location in text file 

None 

Structured file 

None 


@skip_lines 


@skip_lines lets you skip over unneeded lines of text. It copies lines 
into memory and discards them until it finds the termination point 
you specify. 

Syntax 

©skipjmes (termination-point) 

termination-point describes the string or numeric constant that speci¬ 
fies where to stop skipping lines, termination-point can be a pattern 
constant, or a numeric constant. 

• A pattern constant (or a variable that contains the pattern) causes 
©skip Jines to skip to the beginning of the first character that 
matches the pattern. @skip_lines skips over all intervening text 
lines. 
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• A numeric constant causes ©skipjines to skip the specified num¬ 
ber of lines from the current line. For example, specifying 1 (one) 
skips to the next line in the text file, which becomes the current 
line. 

Specifying a pattern as the termination point for @skip_lmes is partic¬ 
ularly useful when you know the pattern for: 

• The start of the text you want to convert 

In this case, the line for which you are searching becomes the 
current text line in memory. This means that you can include the 
commands (@item2, ©note, and so forth) for the current line in the 
same statement. 

• The end of the text you want to skip over 

In this case, the line you wish to convert is the next line after the 
line with the pattern. To skip to this next line, use @skip_lines(l). 

Note After TXT2STF matches the ©skip lines termination pattern 
in a text line, the entire line including the matching string is 
available to the next command. If ©skipjines is the last com¬ 
mand in the statement, the entire matching text line is avail¬ 
able to match the pattern at the start of the next statement. 

Example 

This example shows one way to convert the following text file: 


Message: 123456889766787 

WEEKLY SALES UPDATE: Week of 11/16/90 

Northeast/Mid-Atlantic: 

October goal of 70,000 met due to success of CopyCat and Stratford copiers; 
regional sales meeting Monday 12/3/90. 


The following sample definition file statement is executed when 
TXT2STF finds the string Message: at the start of a text line. 
@skip_lines causes TXT2STF to skip down to the next line. @item2 
creates an item from the current line, and ©note creates a note from 
the remaining text fines, as specified by the predefined variable EOF. 


@skip_lines(1) 
@item2("$") 
@note(EOF) 

@end() 


,,A Message\: ” 
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@start 


When the resulting structured file is imported, it adds the item 
WEEKLY SALES UPDATE: Week of 11/16/90. It adds the remaining 
text as an item note. 

Changes made by this command 


Elements that commands can change 

Changes made by this command 

Current line in memory 

May change the current line to be a later 
line in the text file. 

Item, category, and note buffers 

None 

Variables 

None 

Location in text file 

If @skip_lines specifies a number, 
TXT2STF points to the start of the new 
current line. If @skip_lines specifies a 
termination pattern, TXT2STF points to 
the first character that matches the pat¬ 
tern in the text line. 

Structured file 

None 


©start initializes the item, category, and note buffers. 

Execute ©start before any commands that convert information you 
want to copy to the structured file, so that TXT2STF has buffers in 
which to keep the converted information, ©start is typically the first 
command in the first statement executed in a definition file. 

You can include ©start anywhere else in the definition file where you 
want to initialize buffers without copying their contents to the struc¬ 
tured file. 

Tip To copy the contents of the item, category, and note buffers to 
the structured file, use ©end. 

Syntax 

startO 

©start has no arguments, but the parentheses are required. 
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Example 

The following sample statement starts converting information when¬ 
ever it finds the string To: at the beginning of a line. 


,,A To\: M @start() 

Changes made by this command 

Elements that commands can change 

Changes made by this command 

Current line in memory 

None 

Item, category, and note buffers 

Initializes these buffers 

Variables 

None 

Location in text file 

None 

Structured file 

None 


@strip 


©strip deletes from the text line one or more occurrences of the string 
you identify. 

Syntax 

@stnp(strip-pattern,[number ]) 

strip-pattern describes the string to be removed from the text line. 
strip-pattern must be a pattern constant. You can specify the pattern 
itself, in a pair of quotation marks (’’"), or a variable that contains the 
pattern. 

number (optional) specifies the number of occurrences of the strip 
string to be deleted from the text line, number must be a numeric 
constant. If you omit the number, ©strip deletes all the occurrences 
of the strip string. 
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Example 

This example shows one way to convert the following text file: 


Part-23-17-A 

200/250 filter for Empress humidifier (model #230), with pre-filter attach¬ 
ment for Gen Clean (hospital model #1230/1231) 


The following sample definition file statement executes when 
TXT2STF finds a line starting with the string Part-, which is the word 
Part followed by a hyphen (-). ©strip removes all the hyphens (-) 
from the current text line, @set puts the resulting text into the vari¬ 
able Catname, @custom_category makes the contents of Catname into 
a child of the category Part. @skip_lines advances TXT2STF to the 
next text line. @category_note makes this text line and the remaining 
text lines in the text file into a note for the category, as specified by 
the predefined variable EOF. @end copies the categories to the struc¬ 
tured file. 


"~Part-" @strip{"-",) 

@set("Catname") 

@custom_category(catname,"Component",) 
@skip_lines(1) 

@category_note(EOF) 

@end() 


When the resulting structured file is imported into Agenda, Compo¬ 
nent is added as a child of the current category, as specified when 
you use the Agenda File Transfer Import command. The category 
Part2317A is added as a child of Part. The category note is added to 
category Part2317A. 

Changes made by this command 


Elements that commands can change Changes made by this command 


Current line in memory Deletes from the current line one or more 

occurrences of the identified string 

Item, category, and note buffers None 
Variables None 

Location in text file None 

Structured file None 
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@table 


©table converts information in a table into items and categories. For 
example, you can use ©table to convert a table of information from a 
Lotus 1-2-3 worksheet that has been printed to a text file. 

©table starts processing the table with the current line. TXT2STF 
executes ©table once for each line in the table. To specify where the 
table ends, you include a termination pattern that describes a string 
on the line immediately after the table. 

To convert tabular information, ©table separates the information into 
columns, using the separator pattern you specify. It then processes 
each line in the table, converting the text in specific columns into 
items, categories, and category values. For example, ©table can make 
text in the first column of each line into an item, text in the second 
column into a category, and so forth. 

©table assumes that the first line in the table provides header or label 
information for the column, and converts the columns in that line into 
categories. When ©table processes the remaining lines in the table, it 
assigns items to the category that heads the item column. When 
©table converts text in a category column in the table: 

• For a standard category, ©table makes the text a child of the cate¬ 
gory that heads the category column. 

• For a date, numeric, or unindexed category, ©table makes the text 
a value (for example a date) for the category that heads the cate¬ 
gory column. 

Note ©table adds an item and/or categories to the structured file 
after converting each text line. To do this, ©table internally 
executes an ©start before and an ©end after converting each 
text line. 


Syntax 

@table(separator-pattern,termination-pattern,col-number,type 
[,col-number,type,...]) 

separator-pattern describes the string that TXT2STFuses to divide the 
table. This pattern specifies where a given value ends and another 
begins, separator-pattern must be a pattern constant. You can specify 
the pattern itself, in a pair of quotation marks (" "), or the name of a 
variable that contains the pattern. 
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termination-pattern describes the string that ends the table. 
termination-pattern must be a pattern constant. You can specify the 
pattern itself, in a pair of quotation marks (" "), or the name of a vari¬ 
able that contains the pattern. 

The termination pattern must describe a string on the line that imme¬ 
diately follows the last line of the table. If the text file does not 
include the pattern, TXT2STF processes each line in the text file up 
through and including the last line in the file. 

col-number is a numeric constant that identifies a column to process 
into an item, category, and so forth. To determine the number for a 
column, count the columns in the text file from left to right, using 1 
for the first column, 2 for the second column, and so forth. When 
counting, include all columns, including columns you intend for 
TXT2STF to ignore. 

TXT2STF only converts and copies to the structured file those col¬ 
umns that ©table identifies by number. For each position number in 
©table, you must specify a type. The column number and type 
combinations must all be on the same line as the rest of the ©table 
command. 

type determines whether information in the column becomes an item 
or a category. For categories, this value also identifies the type of 
category to create, type must be a type constant. You can specify 
"date", "exclusive", "numeric", "standard" or "unindexed" for catego¬ 
ries, or "item" for items. 

Example 

This example shows one way to convert the following tabular infor¬ 
mation: 


Table 1: 

Events 

Start Date 

End Date 

COG 

Revenues 

Post-XMAS R 

12/26/89 

12/30/90 

2800 

3200 

Spring Fling R 

04/01/90 

04/15/90 

4500 

8200 

Met Sidewlk Days 

05/02/90 

05/09/90 

4200 

75001 


The following sample statement finds the string Table at the start of a 
line. @skip_lines skips TXT2STF down a line, where ©table starts 
processing the tabular text, ©table divides columns by searching for 
two or more space characters (as specified by the pattern "+) ©ta¬ 

ble makes the first table column the item column, the third column a 
date, and the fifth column a numeric category, ©table ignores the 
second and fourth column. 
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,,A Table" 

@skip lines {1) 



Stable(": +","-+",1,"item 

", 3,"date",5,"numeric") 


When the resulting structured file is imported. Events, End Date, and 
Revenues are added as categories under the current category speci¬ 
fied when you use the Agenda File Transfer Import command. 

Items created from the first column of the table, such as 
Post-XMAS R, are assigned to the Events category. Each item is also 
assigned to the End Date category by the date value on the same row 
as the item, and to the Revenue category by the numeric value on the 
same row. 


See "Converting a Table of Information” in Chapter 3 for another 
example of using ©table. 

Changes made by this command 

Elements that commands can change 

Changes made by this command 

Current line in memory 

When TXT2STF finishes processing the 
table, the current line is the line that 
matched the termination pattern. 

Item, category, and note buffers 

Adds items and categories to TXT2STF 
buffers. 

Variables 

None 

Location in text file 

When TXT2STF finishes processing the 
table, the location in the text file is the 
beginning of the line that matched the 
termination pattern. 

Structured file 

Adds to the structured file after process¬ 
ing each line in the table, adding the item 
and/or categories created from the line. 


@trim 


©trim deletes text from the text line and optionally puts the deleted 
text into a variable. 

This lets you remove unwanted text from the text line before you 
convert the line to be an item, category, or note. TXT2STF then uses 
the entire text line minus the unwanted text (leaving no spaces where 
the text was deleted). 
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You can save the deleted portions of the line in a variable. This lets 
you use the deleted text in a later command or statement. 

To delete text, ©trim locates the specified start and end patterns in 
the text line. It then deletes the text between the patterns. It also 
deletes the pattern text if you instruct it to. 

Each ©trim removes one value from the current line. To remove 
more than one value from a line before you use it, you must include 
more than one ©trim in a statement. 

Syntax 

©trim(s tart-pattern find-pattern \N\[ "variable-name"]) 

start-pattern and end-pattern identify the text to be deleted from the 
current line by giving the starting and ending points for deletion. 
start-pattern describes the string where deletion should start and end- 
pattern the string where deletion should end. Both patterns must be 
pattern constants. You can specify the patterns in a pair of quotation 
marks (" ”), or the name of the variables containing the strings. 

N (optional) specifies that the deletion is not inclusive. N must be a 
logical constant. If you specify N, ©trim deletes the text between the 
specified strings without deleting the strings. If you omit N, ©trim 
deletes from start-string through end-string , including the strings. 

variable-name (optional) identifies a variable into which TXT2STF puts 
the string trimmed from the current text line, variable-name must be a 
variable name string constant. 

Example 

This example shows one way to convert the following sample text file 
to get two categories, Robin McAfee and Anand Mohanty, with the 
address for each person a category note for the category created for 
the person. 


Name: 

Robin McAfee 

Address: 

1234 Main Street 


Anytown, IL 


61820 

Name: 

Anand Mohanty 

Address: 

85 Broadway 


South City, MA 


02042 
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The sample definition file shown below converts this text file. The 
first statement in the definition file is executed when TXT2STF finds 
the string Name: at the start of a text line. Then, ©trim deletes from 
the line everything from the start of the line (specified by the pattern 
" A ") up through the block of spaces that separates the string Name: 
from the actual name (for example, Robin McAfee), ©category makes 
the remaining text line (for example, Robin McAfee) a child of the 
Student Name category. 

The second statement is executed when TXT2STF finds the string 
Address: at the start of a text line, ©category note creates a note that 
starts with the current text line and continues up to (but not includ¬ 
ing) the next name in the file (which is on a line beginning with the 
string Name:), ©end copies the current category and category note to 
the structured file. 


@start() 

@trim(" A ", " +•',) 

gcategory"Student Name",) 

@category_note ( ,,A Name\:") 

@end () 


When the resulting structured file is imported, Student Name is 
added as a child of the current category specified when you use the 
Agenda File Transfer Import command. 

For an example of how ©trim puts a string into a variable, see the 
sample definition file shown at the end of "Writing the Definition File 
Patterns and Commands" in Chapter 1. 

Changes made by this command 


Elements that commands can change Changes made by this command 

Current line in memory Deletes text from the current line 

Item, category, and note buffers None 

Variables Can create new variables or replace the 

contents of existing ones 

Location in text file 
Structured file 


T,A Name\: 


,,A Address \: 


None 

None 
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@unindexed 


©unindexed lets you create assignments to unindexed categories, 
©unindexed specifies the category name and optionally specifies a 
text value. 

When ©end copies the category specified by ©unindexed to the struc¬ 
tured file/ it also copies the item in the item buffer to the structured 
file. When the structured file is imported. Agenda uses the text value 
specified by ©unindexed to assign the item to the unindexed cate¬ 
gory. 

If the unindexed category already exists. Agenda retains the existing 
category and does not create a duplicate category. 

Caution If there is no item in the item buffer when the next ©end is 
executed, then on import Agenda creates the category but 
does not import the text value specified by ©unindexed 
since there is no item to assign to the unindexed category. 

Syntax 

©unindexed (category[,value]) 

category is the name of the unindexed category. This value must be a 
string constant. You can specify the category name, in a pair of quo¬ 
tation marks (”"), or a previously defined variable that contains the 
category name. 

value (optional) is the text value used in the assignment. This value 
must be a string constant. You can specify either the value itself, in a 
pair of quotation marks (" ”), or a previously defined variable that 
contains the value. If you omit value, TXT2STF uses the entire current 
text line in the assignment. 

Example 

The following sample definition file statement creates an assignment 
to an unindexed category. Label, with the text value Al. ©end copies 
the category to the structured file. 


START 


©start () 

©unindexed("Label”,"Al") 
@end() 
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When the resulting text file is imported into Agenda, the unindexed 
category Label is imported as a child of the current category specified 
when you use the Agenda File Transfer Import command. If an item 
is added at the same time, the item is assigned to the Label category 
by means of the text value Al. If no item is added with the unin¬ 
dexed category. Agenda ignores the text value Al. 

Changes made by this command 


Elements that commands can change 

Changes made by this command 

Current line in memory 

None 

Item, category, and note buffers 

Adds an unindexed category to TXT2STF 
category buffers. 

Variables 

None 

Location in text file 

None 

Structured file 

When the next @end is executed, the 
unindexed category is added to the 
structured file. 

If an item exists in the item buffer at that 
time, TXT2STF also adds the item to the 
structured file and assigns it to the unin¬ 
dexed category using the value specified 
by ©unindexed. Otherwise, there is no 
item to assign to the category, and so the 
category is imported into Agenda but the 
associated text value is ignored. 



Chapter 6 

Converting and Importing Text 


Before you import text into Agenda, you can convert the text so that 
Agenda knows which text to use as items, categories, and notes. To 
do this, you run the Agenda TXT2STF utility to convert the text file to 
a structured file. Then, you return to Agenda and import the struc¬ 
tured file using the Agenda File Transfer Import command. 


In this Chapter 


This chapter describes how to convert and import text by: 

• Explaining how to use the TXT2STF utility and its options to con¬ 
vert a text file to a structured file 

• Describing the File Transfer Import command and additional 
options you can specify to control the importing of structured files 

For information about structured files, see Appendix B. For general 

information about converting files to be imported into Agenda, see 

Chapter 23 in the User's Guide . 

Note If you plan to convert a file from an external source (for exam¬ 
ple, a word processing document), make sure it is an ASCII 
text file. Refer to the manuals for the software you use for 
information on how to create an ASCII text file. 


Running TXT2STF 


You run the TXT2STF utility to convert a text file to a structured file. 
You run this utility outside of Agenda, as follows: 

1. Make sure you are in the Agenda program directory. 
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The TXT2STF 
Command 


File Conversion 
Options 


2. At the operating system prompt, type the TXT2STF command, 
following the syntax described in "The TXT2STF Command," 
below. 

TXT2STF displays the TXT2STF copyright box and converts the 
text file to a structured file with the same name and the extension 
.STF. TXT2STF converts the contents of the text file without 
modifying or deleting the original text file. 


The TXT2STF command has the following syntax: 


Syntax 

TXT2STF text file.ext [option(s)] 

textfile.ext is the name of the text file you want to convert. For exam¬ 
ple, if the file name is MEMO.DOC, specify MEMO.DOC for 
textfile.ext. The file must be an ASCII text file. 

options provide additional information to TXT2STF. You can include 
the following types of options in the TXT2STF command: 

• File conversion options give TXT2STF information about how to 
convert the text file. These options are discussed in "File Conver¬ 
sion Options" later in this chapter. 

• Debugging options tell TXT2STF to return debugging information 
when it converts the text file. For more information about these 
options, see "Including Debugging Options" in Chapter 7. 


The following TXT2STF options provide additional information 
about how to convert a text file: 


Option Description 


/C Tells TXT2STF to be case sensitive when matching literal alphabetic 
characters specified in patterns. 

/D Specifies a definition file. A definition file tells TXT2STF how to 

interpret a text file. For more information, see "Specifying a Defini¬ 
tion File" later in this chapter. 

/O Specifies another name for the structured file. For more informa¬ 

tion, see "Specifying a Different Name for the Structured File" later 
in this chapter. 

/S Specifies an alternate separator character for paragraphs in the text 

file. For more information, see "Specifying an Alternate Separator 
Character in the Text File" later in this chapter. 
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How TXT2STF 
Converts Text 
Files 


Specifying a 
Definition File 
to Use with 
a Text File 


Note TXT2STF ignores the /C option when matching a character 
specified as a range or group in brackets ([ ]) and matches 
those characters exactly as specified in the range or group. 
(See Chapter 4.) 

Follow these guidelines when you include options in the TXT2STF 
command: 

• You must use either a slash (/) or a hyphen (-) before each option. 
Correct: 

C:\AGENDA> txt2stf events.txt /o=calendar 

Incorrect: 

C:\AGENDA> txt2stf events.txt o=calendar 

• You can type options in uppercase or lowercase. 

• You can include options in any order. 


If you run the TXT2STF utility without any file conversion options, 
TXT2STF converts each paragraph into an item, putting any text that 
does not fit in the item into a note for the item. The conversion works 
as follows: 

• TXT2STF begins at the beginning of the text file, taking text for the 
first item. When TXT2STF reaches a double carriage return (a 
blank line), it ends the item and starts a new item. 

• If there is no double carriage return before the 350th character. 
Agenda ends the item at the 350th character (the maximum length 
for an item) and puts the remaining text into a note. 

For more information about how TXT2STF processes a text file, see 
Chapter 2. 


The /D option of the TXT2STF command specifies a definition file 
that tells TXT2STF how to convert the text file. You must specify a 
definition file that already exists. For information about how to 
create a definition file, see Chapter 2. 

The /D option has the following syntax: 

Syntax 

/V-definition-file 
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definition-file is the name of the definition file to use. You do not need 
to specify an extension: TXT2STF automatically uses the extension 
.STF. 

Example 

C:\AGENDA> txt2stf memo.all /d=memconv2 

This example formats a text file called MEMO.ALL using the defini¬ 
tion file MEMCONV1.DEF (TXT2STF automatically uses the exten¬ 
sion .DEF. 

Example 

C:\AGENDA> txt2stf news.txt /d=\def\wirenews .def 

In this example, you specify a path since the definition file is not in 
the current directory. The definition file that TXT2STF uses in the 
above example is WIRENEWS.DEF in the DEF subdirectory. 


Specifying a 
Different Name for 
the Structured File 


The /O option of the TXT2STF command specifies another name for 
the output (structured) file. 


By default, TXT2STF converts the text file to a structured file with the 
same name as the text file and the extension .STF; for example, 
MEMO.STF. If this file already contains information, TXT2STF over¬ 
writes the original information in that file when it puts the newly 
formatted text into the structured file. 

Use the /O option if you want the structured file to have a different 
name. You might do this, for example, to save each structured file 
TXT2STF creates for a given text file. 

This is especially useful during debugging, when you run TXT2STF 
each time you change the definition file. If you specify a different 
structured file each time you run TXT2STF, you can compare the 
results of each change you make to the definition file. For more infor¬ 
mation about debugging a definition file, see Chapter 7. 

The /O option has the following syntax: 

Syntax 

/ 0=structured-file 

structured-file is the name of the structured file in which TXT2STF 
puts formatted text. Do not specify an extension; TXT2STF automati¬ 
cally gives the output file the extension .STF. 
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Example 

C:\AGENDA> txt2stf memo.all /o=runl 

In this example, TXT2STF puts formatted text in the structured file 
RUN1.STF, even though the text file is named MEMO.ALL. 

You can also specify a path with the /O option. 

Example 

C:\AGENDA> txt2stf events.txt /o=\stf\calendar 


Specifying an The /S option of the TXT2STF command specifies an alternate sepa- 

Alternate rator character for paragraphs in the text file. When TXT2STF 

Separator encounters two consecutive paragraph separator characters in a text 

Character for a file, TXT2STF begins a new paragraph. 

Text File 


The default separator character is the carriage return (ASCII 
decimal 13). You can use the /S option to specify a different separa¬ 
tor character if the paragraphs in your text file are separated with a 
different character. 

The /S option has the following syntax: 

Syntax 

/ S=separator-character 

separator-character specifies the character TXT2STF uses as the para¬ 
graph separator character. You can use the following as separator 
characters with the /S option: 

• Any keyboard character, such as a comma (,) or period (.) 

• A three-digit decimal ASCII code preceded by a backslash (\) 

Note To use a backslash (\) as a separator character, you must 
enter two backslash characters (s=\\). 

Examples 

C:\AGENDA> txt2stf news.txt /s=. 

The preceding example specifies the comma (,) as the separator char¬ 
acter. Each time TXT2STF encounters two commas in a row, TXT2STF 
starts a new paragraph. 

C:\AGENDA> txt2stf news.txt /s=\010 

The preceding example specifies the three-digit ASCII decimal code 
for a linefeed as the separator character. 
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Converting More You might want to convert more than one text file into a single struc- 
Than One turedfile. For example, you might want to format a group of files 

Text File that each contains information about clients. 

You can convert all the text files at one time if the files have similar 
names. In this case, you can use a wild card character to specify a 
group of files. 

If you want to put the converted files into a single structured file, use 
the /O option when you run TXT2STF. If you omit the /O, TXT2STF 
creates a separate structured file for each text file it converts. 

Example 

C:\AGENDA> txt2stf *.inf /o=allinf 

In this example, TXT2STF converts all files that have an extension of 
.INF, and puts the results in a single structured file named 
ALLINF.STF. 

For more information about wildcard characters, see your operating 
system manual. 


Importing the Structured File 


After you create a structured file, you can import it into an Agenda 
file. Agenda uses the information in the structured file to create 
items, categories, and notes. 

Note Before importing a structured file, make sure you have thor¬ 
oughly debugged the definition file that produced the struc¬ 
tured file, as described in Chapter 7. 

To import a structured file: 

1. Start Agenda and open a file. 

2. Press Flo (MENU) and select File Transfer Import. 

Agenda displays the Import Structured File box, which lets you 
specify the type of information you want Agenda to import from 
the structured file. 

3. Complete the Import Structured File settings and press enter. 
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Agenda imports items and categories from the structured file, and 
assigns the items to categories, according to the choices you specify in 
the Import Structured File settings. You can specify whether you 
want to import everything in the structured file, or only information 
that is new in the structured file since the last time you imported the 
same file. You also use the Import Structured File box to specify the 
types of information to import. 

For details about the File Transfer Import command and the Import 
Structured File box, see Chapter 23 in the User's Guide. 

You can import any or all of the following types of information: 

• Items along with notes 

• Category assignments (assignment of items to existing categories) 

• New categories referenced in assignments 

• New categories that are explicitly created in the structured file 
(created as independent categories and assigned to blank items on 
import) 

You also can use Import Structured File settings to specify 

• A category to which all imported items are assigned 

• The criteria Agenda should use to determine whether categories 
in the structured file match categories in the Agenda file 

• Whether Agenda should eliminate single carriage returns when it 
imports notes 

Note After you import a structured file. Agenda tests items against 
all conditions in the file. If you have a large structured file 
and a complex Agenda file, this can take a significant amount 
of time. You may want to disable conditions before you 
import the structured file. (See Chapter 19 in the User's Guide.) 



Chapter 7 
Debugging 


In this Chapter 


Definition File 


Writing a definition file is like writing a computer program; you may 
need to make some changes before it works the way you want. For 
example, the first time you use the definition file, you might discover 
that TXT2STF converts your text file in a way different from what 
you want. You might find out that it ignores certain items, catego¬ 
ries, or notes that you want converted. 

The process of using a definition file, evaluating the results, and 
changing the definition file to work the way you want is called 
debugging. 


This chapter describes procedures and strategies for debugging a def¬ 
inition file, and provides additional information to help you write 
and debug definition files. 

This chapter describes 

• Procedures for debugging a definition file 

• Testing a definition file 

• Examining the converted information in the structured file 

• Typical problems encountered during debugging and possible 
solutions 


Tips and techniques for writing better definition files 
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Procedures for Debugging a Definition File 


To debug a definition file, you typically perform the following gen¬ 
eral procedures: 

1* Test the definition file by running TXT2STF to convert a sample 
text file. 

2. Look at the resulting structured file to examine the converted 
information that TXT2STF creates. Also note error messages if 
TXT2STF displays any. If the results are not what you want, 
perform Step 3. 

3. Modify the definition file. When you think you've corrected the 
problems in the definition file, return to Step 1. 

This chapter describes how to test the definition file and look at the 
resulting structured file. To modify a definition file, see "Writing the 
Definition File Patterns and Commands" in Chapter 2. 

You perform the above series of steps, modifying the definition file 
and checking the results, until the definition file consistently returns 
satisfactory results. Since TXT2STF does not modify your text file, 
you can run TXT2STF to convert your text file as many times as nec¬ 
essary. 

You may find it helpful to start by running TXT2STF on a small sam¬ 
ple version of your text file. Then, when the definition file correctly 
converts information in that sample, you can test a more complicated 
text file and evaluate the results. 

You are finished debugging your definition file when TXT2STF runs 
without displaying error messages and the structured file contains 
the information you want. At this point, you can import the struc¬ 
tured file into Agenda. If you are developing the definition file for 
other users, you can distribute the definition file to them when you 
finish debugging it. 


Testing a Definition File 


To determine whether a definition file works the way you want, you 
need to try using it with TXT2STF. To name your definition file, 
include the /D option in the TXT2STF command. For more informa¬ 
tion about running TXT2STF, see Chapter 6. 



Debugging a Definition File 7-3 


Naming a 

Structured 

File 


Including 

Debugging 

Options 


TXT2STF puts the text it converts into a structured file. By default, 
TXT2STF creates a structured file with the same name as the text file 
and the extension .STF. For example, TXT2STF creates a structured 
file named MEMO.STF for a text file named MEMO.DOC. 

When you debug a definition file, you may want to name a new 
structured file each time you change the definition file and run 
TXT2STF. This way, you can compare the results of each change you 
make to the definition file. 

To specify a structured file, include the / O option in the TXT2STF 
command. For more information, see "Specifying a Different Name 
for the Structured File" in Chapter 6. 


TXT2STF provides several debugging options to help you see how 
TXT2STF uses your definition file to convert the text file. These 
options tell TXT2STF to display information and return messages 
about its activities while it converts your text file. 

You can specify any or all of the following debugging options when 
you run TXT2STF: 


Option With this option, TXT2STF 

/A Uses all debugging options (/L, /M, /T, /U, and /V) 

/L Displays the current text line when TXT2STF loads or modifies it 

/M Displays the text strings that match patterns that start definition file 

statements 

/T Displays each definition file command when it's executed 
/U Displays each category that TXT2STF creates 
/V Displays the contents of each variable every time it's modified 


For information about other TXT2STF command-line options, see 
Chapter 6. 
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Redirecting Error By default, TXT2STF displays error messages on your screen. So that 
Messages to a File you can examine these messages later, you can redirect them to a file 
by using the redirection symbol defined by your operating system 
(for example, > filename) when you run TXT2STF. 

Example 

C:\AGENDA> txt2stf xfer.txt /d=xfer /a > msgs 

In this example, TXT2STF converts text file XFER.TXT using defini¬ 
tion file XFER.DEF. TXT2STF puts debugging information in the file 
MSGS. 


Examining the Converted Information 


To see how TXT2STF uses the definition file to convert the text file, 
you can examine the results. To do this you can 

• Examine the structured file that TXT2STF creates 

• Examine the debugging information returned by TXT2STF 

• Import the converted information in the structured file into 
Agenda and examine it 


ExaminIng the You examine the contents of the structured file to determine if the 

Structured File definition file made the correct text into items, categories, and notes. 

When you examine a structured file, you see that the structured file 
contains these text elements embedded in special tags that Agenda 
uses to import the text correctly. For example, the {C> tag indicates 
text to be imported as a category. For information about how to read 
the tags in structured files, see Appendix B. 

You can examine a structured file by using any text processor that 
displays text files. If you redirect TXT2STF debugging information to 
a file, you also can examine the file using a text processor that dis¬ 
plays ASCII files. 

If you expect either file to be relatively short, you can use your oper¬ 
ating system type/display command to quickly view the contents of 
the file on your screen. This command typically, however, does not 
let you page back and forth through the contents of a file in the way 
that a text processor does. 


Debugging a Definition File 7-5 


Example 

C:\AGENDA> type outfile.stf ! more 

The above sample command displays the contents of structured file 
OUTFILE.STF. 

If text in the structured file looks different from what you want, you 
need to modify the definition file based on the problems you identify 
in the structured file. Consult "Typical Problems and Solutions" later 
in this chapter for some ideas. 


Importing the When you are satisfied with the contents of the structured file, you 

Converted can import it into your Agenda file. 

Information 


Caution To keep your Agenda file from containing incorrectly con¬ 
verted information, you should wait to import information 
until after the contents of the structured file indicate that 
you have thoroughly debugged the definition file. 

To import the converted information into Agenda, see "Importing a 
Structured File” in Chapter 6. 


Typical Problems and Solutions 


There are three major types of errors that can occur when you run 
TXT2STF with definition files: 

• Syntax errors in statements 

• Pattern matching problems 

• Converting information incorrectly from a text line 

If you have a syntax error in any statements, TXT2STF displays an 
error message. For explanations of TXT2STF error messages, see 
Appendix D. 

Other problems in your definition file, such as pattern matching 
problems, typically cause the structured file to contain incorrect infor¬ 
mation. For example, lines from your text file might be omitted from 
your structured file, or might be converted incorrectly. 
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Testing for 
Pattern Matching 


To find out if a text line matches the intended pattern, create a defini¬ 
tion file that includes only the statement intended to match the line. 
Run TXT2STF using this single-statement definition file, and include 
the /L and /M debugging options. (See "Including Debugging 
Options" earlier in this chapter.) 

• /M shows you exactly where each text line matches a pattern in a 
statement. 

• /L displays the text line if TXT2STF matches it, and every time 
TXT2STF changes it. 

If the text line does not match the intended statement, you need to 
modify the pattern in the statement. 

If the text line does match the statement, consider whether: 

• An earlier statement in the original definition file matches the 
text line. 

In this case, TXT2STF uses the earlier statement to convert the text 
line and never uses the intended statement. Remember that once 
TXT2STF finds a pattern that matches the text line, it does not 
search any further. 

Try refining the patterns or changing the order of statements in 
the definition file. Make sure that statements that include the gen¬ 
eral patterns occur after statements with specific patterns in the 
definition file. For more information about statement order in 
definition files, see "Tips and Techniques" later in this chapter. 

Also check @skip_lines commands in previous definition file 
statements to see whether they cause TXT2STF to skip over the 
line you want to convert. This occurs if ©skip lines matches a 
pattern on the line you want to convert or on a later line in the text 
file. To fix this problem, you can generally put the converting 
commands in the same statement as the ©skipjines command. 
The /L option can tell you where the @skip_lines command 
skipped to. 


Some reasons why lines from your text file might not be copied to the 
structured file include: 

• The line is not converted, and thus not copied, because it does not 
match the intended pattern. 

• The line matches the pattern, but is never tested against that pat¬ 
tern. 
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Testing How 
Information 
Is Converted 


• The commands in the intended statement convert information dif¬ 
ferently from what you want. 

In this case, you can examine the information returned by the /L 
debugging option to see how the text line is modified by com¬ 
mands. For additional solutions, see "Testing How Information Is 
Converted." 

To determine if either or both of these situations apply, you can 
examine the original definition file. Also, consider running TXT2STF 
again, using the original definition file and the /L and /M options. 


Even though a text line matches the intended statement, the com¬ 
mands in the statement may not convert the line in the way you 
want. There are several reasons why this might occur. 

To find out why information is converted incorrectly, you need to 
analyze how each command in the statement converts the text. For 
each text line that is not converted how you want, run TXT2STF using 
a definition file that includes only the statement intended to convert 
the text line. Also include debugging options in the TXT2STF com¬ 
mand. (See "Including Debugging Options" earlier in this chapter.) 

• To focus on how the text line is formatted, include the /L /T, and 
/V options in the TXT2STF command. 

/T displays each command when TXT2STF executes it. /L dis¬ 
plays the contents of the text line each time TXT2STF changes it. 

/V displays the contents of each variable whenever TXT2STF 
modifies the variable. This is important if you use variable com¬ 
mands, such as @grab, to convert text lines. 

• To see how TXT2STF creates categories, consider turning on all 
debugging options by including the / A option in the TXT2STF 
command. 


/A provides the most complete debugging information. In early 
stages of debugging, however, this option may provide more 
information than you need. 

Typical reasons why a text line is converted differently from what 
you want: 

• The line might be altered incorrectly by a trimming command. 

For example, the command might trim text that you want to con¬ 
vert. The /L option helps you find this problem by displaying the 
current line after each trimming command changes it. 


I 
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• Commands such as ©grab and ©trim, which create variables, 
might incorrectly put values into variables. 

The /V option helps you find this problem by displaying vari¬ 
ables each time they are created or modified. If this occurs, it is 
likely that you need to modify an argument in the command, such 
as the separator pattern in ©grab or the start and end patterns in 
trim. 

• An ©skip Jines command might make the text line unavailable. 

A @skip_lines in the current definition file statement might skip 
over the text line you want to convert. In this case, the line is 
unavailable for conversion. Use the /L option to see which line 
©skip lines skips to. 

• Patterns included as parameters within commands might require 
adjustment. 

For example, you can specify a pattern to tell TXT2STF where an 
item or a note ends. If these patterns are incorrect, TXT2STF con¬ 
verts different portions of text than the portions you want. 


Tips and Techniques 


This section lists suggestions to help you write better definition files. 


Writing Patter n S In general, it is a good idea to write patterns that explicitly describe 
the text to be matched. Include in the pattern as many actual charac¬ 
ters from the string as you can. Specifying explicit patterns increases 
the likelihood that the correct text lines will match the pattern. 

Even when using a generic pattern, try to be as exact as possible. For 
example, consider the generic pattern used in the sample definition 
file constructed in Chapter 1. That pattern, matches lines 

starting with either To: and From: and thereby enables you to write 
one statement to handle two different text lines. 

However, this pattern really matches an entire text line, as specified 
by the combination caret ( A ), period (.), and asterisk (*). Then, 
TXT2STF searches the line backward, character by character, to find a 
colon (:). (The backslash (\) tells TXT2STF to match the colon (:) as a 
text character and to ignore its special meaning in match-control 
characters.) The matching string consists of the entire line up to the 
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last colon {:) in the line, which is acceptable for the example in 
Chapter 1, but could cause problems for text lines that include more 
than one colon (:). 

A different pattern that also matches To: and From: is 
" A [ A : ]*\:", which matches an entire text line up through the first 
colon (:). This pattern starts at the beginning of a text line, and 
matches each character that is not a colon (:). If it finds a colon (:) in 
the line, the text from the start of the line up to the colon (:) matches 
the pattern. If the line does not contain a colon (:), the line does not 
match the pattern. (See "How TXT2STF Compares Patterns with 
Strings" in Chapter 4.) 

Other tips for writing patterns: 

• Analyze negative patterns carefully. 

A negative pattern uses the tilde (—) to match text that is not the 
pattern. Typically, many text lines can match a negative pattern. 
For example, the pattern " A ~Tuesday" matches any line that does 
not start with the word Tuesday. 

When you need to use a negative pattern, anchor the pattern to a 
fixed characteristic of the string, such as the start or end of the 
line. This makes the pattern more likely to match only those text 
strings for which it is intended. 

When you use a statement starting with a negative pattern, make 
sure the statement is located toward the end of the definition file. 
For more information about negative patterns, see the discussion 
of the tilde character in Chapter 4. 

• If you need to use a complicated pattern more than once as an 
argument in definition file commands, consider using ©equate to 
assign the pattern to a variable. This way you need to debug the 
pattern only one time. You can then use the variable that contains 
the pattern in every command where you need the pattern. Fur¬ 
thermore, if you need that pattern in another definition file, you 
can copy the ©equate command into that definition file and use 
the variable there. 


The order of statements can significantly affects how the definition 
file converts text lines in the file. 

This is because the definition file does not operate like a procedural 
program, but more like a list of different actions to take when 
TXT2STF finds specific text strings in a text file. Each definition file 
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statement describes an action to take. When TXT2STF matches a text 
line with a definition file statement, it executes the commands in the 
matching statement. 

Each definition file statement begins with a pattern that describes the 
line to be converted by the statement. TXT2STF converts a text file 
line by line, one text line after the other. For each new text line to be 
converted, TXT2STF compares the line to statements in the definition 
file, starting from the beginning of the definition file, searching for a 
pattern that the text line matches. 

For this reason, it is important to organize the statements so that the 
first pattern matched by a text line is the correct pattern. In general, it 
is a good idea to put specific patterns, which exactly match particular 
lines, early in the file. This way, text lines for which specific patterns 
exist match their patterns right away. 

Sometimes it is useful to have a statement match more than one line. 
For example, you might want to match both the To and From lines in 
an electronic mail file and use the same commands to convert both 
lines into categories. 

Statements that are generic enough to match more than one lines 
should be put toward the end of the definition file. Statements with 
specific patterns should be put toward the start of the definition file. 
This way TXT2STF compares a text line with all specific patterns, 
which are early in the definition file, before comparing it with generic 
patterns. 


Skipping When converting text in a text file, you might need to skip over text 

Over Text on a specific text line. You also might need to skip over entire lines of 

text. 

If you need to selectively convert portions of a single text line, use 
trimming commands such as ©trim, ©skip, ©strip, and ©replace, 
©trim is especially useful, since it saves the text it trims in variables 
so you can use the trimmed text later in the file conversion process. 

Put the trimming commands for a text line before any commands that 
convert the line into item text, a category, or a note. 

If you need to construct a single item, category, or note from text that 
is separated by intervening material in the text file, construct your 
statement as described below. 

• Use the pattern to locate the start of the item, category, or note, 
and use the appropriate command to convert it. 
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• Next use the @skip__lines command to skip over the irrelevant 
material. You can delete several lines of unwanted text in the 
middle of an item or note. 

• Finally, use another @item2 or ©note command to append the rest 
of the text to an item or note. 

For example. Figure 7-1 shows a sample text file. 


Name: 

Lynne George 

Req: 

Job Posting FA-1290 

Address: 

10 Holstream Rd. 

Jamaica Plain, MA 02130 

D.O.B: 

4-7-58 

Social Security: 

123-45-6789 

Degree Program: 

Fashion Design 

Work Experience: 

A.R.T. costumes 

Comments: 

Lynne has taken two semesters 
of Pattern Making 


Figure 7-1 Sample text file 


Figure 7-2 shows a definition file that makes the name into an item, 
starts a note at the Req line, and then skips the information until 
D.O.B. It puts information until Degree into the note, then makes the 
degree program a category. The text following the degree is 
appended to the note that was started above. 
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Handling More 
Than One 
Text Layout 


#Convert student information to .STF format 

#Skip over "Name:” and make item from name on the line 

, "'Name\:” @start{) 

@skip("\: +”,1) 

@item2("$") 

#Start note after skipping "Req:", skip over address, 
#and add DOB to Degree into note 

" A Req\:" @skip{"\: +",1) 

@note("$") 

@skip_lines(" A D.O.B") 

@note("^Degree”) 

#Skip over "Degree Program:" and make degree into 
tcategory under category Program 

" / 'Degree" @skip("\: +",1) 

@category,"Program", ) 

#Add all of Work experience and Comments lines to end 
#of note 

" A Work" @note("Name") 

Send() 


Figure 7-2 Definition file for converting student information 
text file 


When the resulting structured file is imported into Agenda, the name 
Lynne George is added as an item and is assigned to the category 
Fashion Design. The item has a note that contains various informa¬ 
tion about the candidate Lynne George. The category Fashion Design 
is added as a child of Program, which is itself a child of the current 
category specified when you use the File Transfer Import command. 


You may need to write a definition file that can handle more than one 
text layout. For example, it might need to convert electronic mail 
messages whose topics are labeled either by Subject: or Re:, or that 
end in several different ways depending on the electronic mail 
source. 

When you add statements to the definition file, make sure you add 
statements whose patterns match each differing layout. For example, 
add a statement that matches and converts a topic line that starts with 
Subject:, and another statement for a topic line that starts with Re:. 
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If the text can end in more than one way, include a statement of the 
form: 

END @end() 

The above statement executes ©end, and copies the current item to 
the structured file when TXT2STF reaches the end of the text file. 
Without an ©end, TXT2STF stops processing the text file without 
copying the item it created to the structured file. 


Creating More 
Than One 
Item 

To create an item, you add statements to the definition file, each of 
which converts appropriate lines in the text file. Commands in each 
statement create the item, an item note, and one or more categories 
from the text file, as appropriate. 

After the definition file creates each item, it should execute an ©end 
to copy the item to the structured file. Then, TXT2STF can create 
another item by converting the next text lines in the text file. 

If the text can end in more than one way, it might be useful to end 
each item by searching for the start of the next occurrence of text in 
the file (for example, the next electronic mail message). Then, make 
©end the first command in the statement followed by the commands 
that convert the matched text line. To write the very last item to the 
structured file, include a statement of the form: 

END @end() 

The following strategies describe typical situations when you may 
want to create more than one item from a text file: 

• The text file contains multiple occurrences of the same type of 
information (for example, several electronic mail messages). 

In this case, each message has basically the same layout and can 
be converted by the same group of statements. At the end of each 
item (for example, the end of each message), execute @end. End 
the definition file with the statement END ©end, as described 
above. 

• The text file contains different types of information (for example, 
both electronic mail and telex messages). 


You may want to create more than one item from the information in a 
text file. For example, a text file can contain several electronic mail 
messages, in which case you might want to create a new item for each 
message. 
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In this case, you must add definition file statements that can han¬ 
dle each type of information in the file. 

If the types of information differ significantly in layout, you may 
need to organize the statements for each layout into separate 
groups, each with its own pair of ©start and ©end commands. 
Even if differences in the file formats do not require separate state¬ 
ment groupings, you might prefer to group them separately to 
improves the readability of the definition file. 



Appendix A 

What’s New in TXT2STF for Agenda 2.0 



New features have been added to TXT2STF to support Agenda 2.0 
features and also to enhance TXT2STF performance and give you 
greater control over how TXT2STF converts text files into structured 
files. 


In this Appendix 


This appendix describes changes in 

• Running TXT2STF 

• Definition files, including changes in patterns and commands 
(previously called actions) 

• Structured file tags 


Running TXT2STF 


You run TXT2STF to convert the contents of a text file into items, 
categories, and notes. TXT2STF puts the items, categories, and notes 
in a structured file, which you can then import into Agenda. 

The following differences apply whenever you run TXT2STF: 

• TXT2STF runs faster than in Agenda 1.0. Comments in definition 
files do not slow performance. 

• New error and warning messages describe situations that arise 
when TXT2STF converts a text file to a structured file. (See 
Appendix D.) 


A-1 
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• New debugging options for use with definition files replace the 
TXT2STF debugging options used in Agenda 1.0 (see below). 

TXT2STF still supports the /C, /D, and /O command-line options 
that you can use whenever you run TXT2STF (even when you do not 
use a definition file). For more information about running TXT2STF 
and using these options, see Chapter 6. 

You also specify TXT2STF debugging options in the TXT2STF com¬ 
mand line. The new TXT2STF debugging options are 


Option With this option , TXT2STF 

/ A Uses all debugging options (/L, /M, /T, /U, and /V) 

/L Displays the current text line when TXT2STF loads or modifies it 

/M Displays the text strings that match patterns that start definition file 

statements 

/T Displays each definition file command when it's executed 
/U Displays each category that TXT2STF creates 
/V Displays the contents of each variable every time if s modified 


For more information about TXT2STF debugging options, see 
Chapter 7. 


Definition Files 


You can create definition files to give TXT2STF instructions about 
how to convert text files into structured files. 

When you continue a definition tile statement to another line, you no 
longer need to start the continued line with a backslash (\). (You still 
must, however, make sure that you split the statement between com¬ 
mands and that you don't split a command to two lines.) TXT2STF 
still accepts backslashes (\) at the start of a line, so you do not need to 
remove the backslashes (\) from existing definition files. 



Patterns 
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Patterns describe a text string that you want the definition file to 
match. For details about patterns see Chapter 4. 

Changes have been made to the match-control characters you can 
specify in a pattern and to the number of character classes you can 
include in a pattern. 




Match-control characters 

The following changes have been made to match-control characters: 


Match-control character 

Changes 

Caret ( A ) 

Must be the first character in the entire pattern; for 
example " A Hardware ! A Software" must now be 
written as " A (Hardware ! Software)" and 
"Re\: ! A Subject\:" must be " A Subject\:! Re\:” 

Dollar sign ($) 

Must be the last character in the entire pattern; for 
example "follows$ ! below$" must now be written as 
"(follows ! below)$" and "emblem$ ! sign" must be 
"sign i emblem$" 

Exclamation point (!) 

No longer supported as the NOT character (see Tilde, 
below) 

Parentheses () 

Can be a maximum of 10 nesting levels defined by 
nested parentheses in a pattern 

Square brackets ([ ]) 

Is always case-sensitive, regardless of whether you 
specify the /C command line option in the TXT2STF 
command 

Tilde <~) 

(New) Matches any line that contains a string that is 
not the pattern; creates a negative pattern, but works 
differently than the exclamation point (!) did in 
Agenda 1.0 


Character classes 

A character class is defined by colon a (:a), colon d (id), colon n (:n), 
colon space (: ), and by each range/group specification made in 
brackets ([]). TXT2STF now restricts you to a maximum of eight 
character classes per command. 
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Definition File 
Commands 


Definition file commands, called actions in Agenda 1.0, tell TXT2STF 
how to convert the current line into item, category, or note text. For 
details about definition file commands, see Chapter 5. 

With Agenda 2.0, you have more flexibility in using variables in com¬ 
mands. Several new commands have been added and existing com¬ 
mands have been changed to let you take advantage of new Agenda 
and TXT2STF features. 

Variables 

You can now take much more advantage of variables in TXT2STF 
commands. For example, you can now use ©trim to put text from a 
text line in a variable, which lets you use the trimmed text in later 
commands or statements. New commands ©append and ©grab put 
text in variables, which makes it easier to use variables as arguments 
in definition file commands and gives you more flexibility in writing 
definition files. 

New commands 

TXT2STF provides the following new commands: 


New command 

Description 

©append 

Adds a string to the end of the current contents of the 
variable 

@append_item 

Appends a string to the end of the item currently being 
constructed from the text file 

@append_note 

Appends a string to the end of the current note 

©grab 

Divides the current text line into several values, and puts 
each value into a variable 

@item2 

Creates an item using text from the text file; is an alterna¬ 
tive to ©item that provides greater control over how 
TXT2STF constructs an item 

©numeric 

Creates an assignment to a numeric category 

©unindexed 

Creates an assignment to an unindexed category 
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Changed commands 

Changes and enhancements have been made to the following com¬ 
mands: 


Existing command 

Changes made to the command 

©category 

and 

@custom_category 

Can specify the ancestors of a parent category (en¬ 
hancement to the second argument) 

Can now create "date", "exclusive", "numeric", "stan¬ 
dard", and "unindexed" categories (enhancement to 
the third command argument) 

©date 

Can now name any date category and optionally 
identify a date value (such as 11/01/90) for the date 
category (enhancement to the first command argu¬ 
ment; new optional second argument) 

@make_extemal_note 

Can now create note files that contain more than 
10,000 characters 

©table 

Gives you greater flexibility in converting tabular 
information and lets you create any type of category 
(new argument list) 

©trim 

Can put trimmed text in a variable (new optional 
fourth argument) 


Structured File Tags 


A structured file contains text for items, categories, and notes. This 
text is embedded in structured file tags, which tell Agenda how to 
import the text. 
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Changes have been made to the following structured file tags: 
Tag Change 


{C} {C} can now create date, exclusive, numeric, standard, and unin- 

dexed categories. For date, numeric, and unindexed categories, the 
final term in the category specification is the value associated with 
the category, such as the date. 

Special characters specify the type of category to create. The escape 
character (%) lets you include any of these special category charac¬ 
ters as normal text characters if necessary. 

{STF) (STF) specifies header information for the structured file using a new 
format. This new header tells Agenda that the structured file con¬ 
tains structured file tags for Agenda 2.0. 

Agenda still accepts structured files created with the Agenda 1.0 
header; however, if the structured file contains Agenda 2.0 struc¬ 
tured file tags, the information may be imported differently than 
how you want. For example, date, numeric, and unindexed 
_categories would be imported as unindexed categories. 
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TXT2STF converts text from a text file, placing the converted text in a 
specially formatted file called a structured file. A structured file con¬ 
tains text that is structured in a way that Agenda can import. 

After you create a structured file, you use the Agenda File Transfer 
Import command to import the structured file. For more informa¬ 
tion, see "Importing the Structured File" in Chapter 6. 

You can also use your own software products or tools to create a 
structured file. In this case, you must create a structured file that 
conforms to the layout described in this chapter. 

This appendix provides information to help you examine a structured 
file when you debug a definition file. It also provides information 
you need to know if you are creating your own structured file. 


In this Appendix 


This appendix describes the layout of structured files by providing 

• An overview of structured files 

• A description of structured file tags 

• Sample structured files that you can use to see how text in a struc¬ 
tured file typically looks 


About Structured Files 


A structured file includes information that is ready to be imported 
into Agenda. TXT2STF creates a structured file whenever you run 
TXT2STF to convert a text file or when you export from Agenda. 


B-1 
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You need to be familiar with structured files and what they contain 
when you debug a definition file. By examining the definition file, 
you can quickly see how TXT2STF interprets the definition file state¬ 
ments. For example, you can see whether TXT2STF converted the 
proper text into items and assigned items to categories in the way 
you want. 

You should also be familiar with structured files if you create your 
own structured files using a programming language, such as BASIC 
or PASCAL. The program you write to create the structured file must 
structure text so that Agenda can import the text in the way you 
want. 

For more information about importing a structured file, see "Import- 
ing the Structured File" in Chapter 6. For additional information 
about importing files, see Chapter 23 of the User's Guide. 

Note If users are sharing a structured file on a Local Area Network 
(LAN), they all can see the contents of any structured files, as 
long as the structured files are unprotected. However, only 
the first user to open a structured file can modify it. Thus, if a 
file is being modified, other users can see the file and use its 
contents but cannot make changes to it. Changes made to the 
structured file cannot be seen by other users on the LAN until 
the user making the changes exits from the structured file. 

For information on file reservation, see Appendix F of the 
User's Guide. 


A structured file contains text to be imported into an Agenda file, 
with tags that tell Agenda how to import the text. For example, tags 
specify which text to use as items, categories, and notes, and which 
date format to use when importing dates. 

Structured file tags are special codes that provide instructions to 
Agenda. Each structured file tag is enclosed in a pair of braces ({}); 
for example, {I}. Structured file tags can create 

• One or more items, each item having related categories and a note 

• One or more independent categories (not assigned to items) 

• Independent notes (attached to blank items on import) 

A structured file can contain tags to create any or all of these. 

You can examine a structured file using any text processor that can 
read ASCII text files. It is very helpful to look at a structured file 
when you are debugging the definition file that created it. 


What a 
Structured 
File Contains 
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Creating Your You can create your own structured file. This may be useful, for 

Own Structured example, if you have a text file that cannot easily be formatted using 

File TXT2STF (for example, you need to perform branching or conditional 

operations), or if you are already familiar with a programming lan¬ 
guage such as BASIC or PASCAL, and would prefer to use that lan¬ 
guage. 

If you create your own structured file, keep in mind that the file must 
be a text file, must include structured file tags in the proper format, 
and must have an extension of .STF. 


Structured File Tags 


Structured file tags tell Agenda how to import the text in the struc¬ 
tured file. For example, the (C) tag tells Agenda that the immediately 
following text should be imported as a category. The {N} tag 
indicates where note text begins. 

Agenda provides structured file tags that 

• Begin a structured file 

• Create comment text (a block of text that contains information that 
Agenda ignores on import) 

• Specify the format of dates in the structured file, so Agenda can 
correctly import subsequent dates 

• Create notes 

• Create categories (category and family, with any associated notes) 

• Create items (item and associated categories, notes, and dates) 

TXT2STF includes structured file tags in text when it copies the con¬ 
tents of the current item, category, and note buffers created by 
converting a text file to the structured file. If you construct your own 
structured file, you must make sure to include the correct tags. 

The following table lists the tags that can be included in structured 
files. Tags must be in the same case (lowercase or uppercase) as 
shown in this table. 
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Tag Meaning 

fd) Specifies a date format, such as MM/DD/YY 

{Q Beginning of a category specification (the category and family, with 
any associated notes) 

fD> Done date 

{F} Beginning of a category note 

{E} Entry date 

{G} Name of the note file for the category 

11} Beginning of an item specification (the item and associated catego¬ 
ries, and notes) 

(NT} Beginning of an item note 

{O} Name of the note file for an item 

IS} Beginning of comment text to be ignored when imported 

{STF} Header that begins a structured file 
IT} Beginning of the text of an item 

{W} When date 

(.} End of a category specification 

{!} End of an item specification 

Figure B-l shows a sample structured file containing structured file 
tags. This example contains information converted from a sample 
MCI Mail® file. 
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Structured File 
Header Tag 


#Processing electronic mail messages 

{STF} 11 /19/90;11:54:49;002 

{ 1 } 

{T} Weekly Sales Update 

{C}\cc\ Alan Stewart % / MCI ID: 234-5678{.} 

{C} \To\ Pam Crawford %/ MCI ID: 567-8901 {.} 

{C}\To\ * Paul Kyn %/ MCI ID: 890-12341.} 

{C}\From\ Lynne George %/ MCI ID: 123-4567{.) 

{C}\Entry@ ! Mon November 19,1990 9:24am GMT{.) 

{C}\MaiI\E-Mail{.} 

{N} WEEKLY SALES UPDATE: Week of 11 /16/90 

N ortheast / Mid- Atlantic: 

October goal of 70,000 met due to success of CopyCat and Stratford copiers; 
hiring of two new personnel for fall school promotions (Henry Clarkman — 
Hartford, Ct., Jennine Powell, New York City schools); regional sales meeting 
Monday 12/3/90. 

0 } 


Figure B-l Sample structured file 


The above sample creates a single item, whose text is Weekly Sales 
Update. It adds the item to the cc. To, From, and Mail categories, and 
assigns it an Entry date of Mon November 19,1990. All text after the 
{N} is a note for the item. The entire item specification starts with {1} 
and ends with {!}. 

The remainder of this chapter describes the types of tags that can be 
included in a structured file, and gives additional information about 
how Agenda interprets tags and the structured information they 
identify. 


{STF} starts a structured file. This tag must be the tag in the struc¬ 
tured file. The following information occurs on the same line, imme¬ 
diately after this tag: 

• The date and time when the structured file was created; the date is 
in MM/DD/YY format and the time uses a 24-hour clock 

• A revision number that tells Agenda which revision of structured 
file tags are in the file; for Agenda release 2.0, this revision num¬ 
ber value must be 002 (with leading zeros) 

A semicolon (;) separates the date from the time and the time from 
the revision number. 

Note If the header is incorrect, structures new to Agenda Release 
2.0 will not be imported as expected. For example, all date 
and numeric categories are imported as unindexed categories. 
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Comment Tag 


Date Format Tags 


Figure B-2 shows a sample structured file header line. 


{STF} 11/02/90;! 5:20:11;002 


Figure B-2 Sample header line 


If you create your own structured file, make sure you use the format 
shown in Figure B-2. Notice that the date must be in the default 
Agenda format of MM/DD/YY, and that the header must end with 
the number 002. 


{S} begins comment text in the body of the structured file. Comments 
let you describe what a structured file or its tags do. For example, 
you can include comments to describe how a group of tags organizes 
information to be imported. 

Agenda ignores comment lines when it imports information from the 
structured file. Agenda ignores any text between {S} and either the 
next tag in the structured file or the end of the structured file. 


Date format tags specify the format of dates and times in the struc¬ 
tured file. On import. Agenda uses the date format specification to 
interpret dates in the structured file. 

By default. Agenda assumes that dates in the structured file are in the 
format MM/DD/YY and use a 24-hour clock. If dates in the text file 
have a different format, the structured file must specify the format 
before specifying any date values. You can omit date format tags if all 
dates are specified either in the default format (MM/DD/YY) or in a 
combination of words and numbers, as in "Thursday November 8 
1990". 

Note The date format tag does not affect the date and time speci¬ 
fied in the {STF} tag, which must specify a date in 
MM/DD/YY format and time using a 24-hour dock. 

TXT2STF adds a date format tag to the structured file when it 
executes @date_format command in a definition file. 

The following table lists the valid date format tags and the date for¬ 
mats they specify. 

Note These are only a subset of the date formats supported by 
Agenda. (See Chapter 7 in the User's Guide.) 
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Format number 

Associated date format 

Associated time format 

1 

MM/DD/YY 

24-hour clock 

2 

DD/MM/YY 

24-hour clock 

3 

DD.MM.YY 

24-hour clock 

4 

YY-MM-DD 

24-hour clock 

5 

DD-MMM 

24-hour clock 

6 

DD-MMM-YY 

24-hour clock 

7 

MM/DD/YY 

12-hour clock 

8 

DD/MM/YY 

12-hour clock 

9 

DD.MM.YY 

12-hour clock 

10 

YY-MM-DD 

12-hour clock 

11 

DD-MMM 

12-hour clock 

12 

DD-MMM-YY 

12-hour clock 


Note Each date format tag must contain a lowercase d, and must be 
immediately followed by the format number as shown in the 
above table. 

Figure B-3 shows an example of using date format tags. 


{d}2 

{C}\Activity Date® ! 15/11/90 {.} 

{C}\Start Date® ! Thu November 15,1990 3:44pm GMT.{.} 
{d}l 

{C}\Start Date®! ll/19/90{.) 


Figure B-3 Sample date format tags 


The example in Figure B-3 begins with a {d}2 tag, which specifies that 
the structured file contains dates in the format DD/MM/YY. The 
next two {C} tags create date categories; each category specification 
starts with {C> and ends with {.}■ The {d}2 tag applies to the first {C> 
in the pair, which adds a date in the DD/MM/YY format. The {d}2 
tag does not apply to the second (C) specification, since the date 
value in that specification contains both words and numbers. 
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The {d}l tag then changes the date format to MM/DD/YY format. 
This tells Agenda that subsequent date values in the structured file 
are in MM/DD/YY format. This {d}l enables Agenda to import the 
date in the immediately following {C} specification, which is in 
MM/DD/YY format. 

For more information about the fC) tag for specifying categories and 
dates see "Category Tags" later in this Appendix. 


Note Tags Note tags identify note text to be imported, or the name of a note file 

to be used by an item or category. The following table lists the note 
tags that can be included in a structured file. 


Tag Meaning 


{F} Beginning of a category note 

{G} Name of the note file for the category 

{N} Beginning of an item note 

{O} Name of the note file for an item 


Caution A note can be a maximum of 10,000 characters. When 

Agenda imports a note that is longer than this maximum, 
it truncates the remainder of the imported note text when 
the note reaches 10,000 characters in length. Item text can 
contribute to the size of a note, as described in "Item Tags" 
later in this chapter. 

Category notes 

{F} and {G> identify category notes and must occur between tags that 
create a category. (See "Category Tags" later in this appendix.) 
Agenda adds the note to the specified category. If more than one 
category note tag occurs in the category specification, Agenda uses 
only the last one and discards the preceding note tags. 

{F} starts a regular note. The note text to be imported follows imme¬ 
diately after, on the same line. Agenda assumes that all remaining 
text is note text until it encounters another structured file tag or 
reaches the end of the structured file. 

fG} identifies an external file to be attached as a note file. If {G} 
identifies a note file that does not exist, Agenda asks you whether 
you want to create it when you attempt to look at the note in the 
Agenda file. 
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Figure B-4 shows sample category note tags in a category specifica¬ 
tion. 


{C}\Client\ 

{G}c:\Agenda\clients.lst 

U 


Figure B-4 Sample category note tags 


In Figure B-4, {C} and {.} begin and end the category specification, as 
described in "Category Tags” later in this appendix. Within the cate¬ 
gory specification, (G) instructs Agenda to make external file 
AGENDANCLIENTS.LST the note file for the Client category. 

Item notes 

{N} and {O} identify notes. The location of the note tag determines 
what Agenda does with the imported note. 

• If the tag occurs between item tags, as described in "Item Tags," 
Agenda adds the note to the item. 

• If the tag occurs outside of an item specification, Agenda creates 
an empty item and adds the note to that item. This lets you 
import a note without assigning it to an item or category. 

If more than one note tag appears in an item specification. Agenda 
uses only the last one and discards the preceding note tags. 

{N} starts a regular note. The note text to be imported follows imme¬ 
diately after, on the same line. Agenda assumes that all remaining 
text is note text until it encounters another structured file tag or 
reaches the end of the structured file. 

{O} identifies an external file to be attached as a note file. If fO) 
identifies a note file that does not exist. Agenda asks you whether 
you want to create it when you try to look at the note in the Agenda 
file. 

Figure B-5 shows sample item note tags in an item specification. 
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Category Tags 


ffl 

{T} Sales Reward Dinner 
{N} Allgrands Hearthside Inn 
1234 Highway 1 
West Linton, WA 

(fust past the Lighthouse Mall on the left) 

W 


Figure B-5 Sample item note tags 


Figure B-5 defines an item, Sales Reward Dinner, and defines a note 
describing the location of the restaurant where the dinner will be 
held. On import. Agenda adds the note to the item because {N} is 
included between the {1} and {!} item tags that create the item. For 
more information see "Item Tags" later in this chapter. 


Category tags create a category and its family, along with any asso¬ 
ciated category notes. The location of the category tags determines 
what Agenda does with the imported category. 

• If the category tags occur between tags that create an item, as 
described in "Item Tags," Agenda assigns the item to the category. 

• If the tags occur outside an item specification. Agenda adds the 
category as an independent category to the category hierarchy, 
but does not assign the categories to an item. 

For more information see "Item Tags" later in this chapter. 

The following tags create a category: 


Tag Meaning 

{C} Beginning of a category specification (the category and family, with 
any associated notes) 

{.} End of category specification 


Each {C} begins a new category specification. The name of the cate¬ 
gory to be imported follows immediately after, on the same line. 
Each category ends with a {.} tag. If category note tags {F} or {G} 
occurs between {C} and {.}, Agenda adds a note to the category on 
import. 



Structured Files B-11 


When you use the File Transfer Import command, you can specify 
whether Agenda should import either or both of the following types 
of categories: 

• New categories created in item specifications 

• New independent categories 

Agenda imports the categories you specify and adds them to the cate¬ 
gory hierarchy. For more information, see Chapter 23 in the User's 
Guide. 

If the category is created in an item specification. Agenda assigns the 
item to the category on import. If the category is a date, numeric, or 
unindexed category. Agenda uses the associated value, such as the 
date, to assign the item to the category. 

Caution If a date, numeric, or unindexed category is specified out¬ 
side of an item specification. Agenda creates the category 
if appropriate, but does not import the associated numeric, 
date, or unindexed value. 

If the structured file identifies a category that already exists. Agenda 
retains the original category on import, and does not import the 
duplicate category. 

Category characters 

Special category characters in the category name tell Agenda the type 
of category to create. 


Category Character 

Meaning 

\ 

Standard category 

/ 

Exclusive 

1 

Unindexed 

# ! 

Numeric 


Date 


The category character immediately follows the category to which it 
applies. For example, the following text after a {C} tag adds Date 
Delivered as a date category: 
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Date Delivered® ! 

To indicate parent and child relationships in category information, 
the {C} tag separates each parent name from its child by using the 
appropriate category character. In date, numeric, and unindexed 
categories, the category character separates the category name from 
the associated value. For example, the following text after a {C} tag 
adds the Date Delivered category with a value of 11/26/90: 

Date Delivered® ! 11/26/90 

If the structured file identifies a new parent category. Agenda creates 
the parent category when it imports the structured file. 

If the category specification begins with the standard category charac¬ 
ter, the backslash (\), Agenda imports the category as a child of 
MAIN. For example: 

{C}\From\ Terry Smith {.} 

In the above example, the backslash (\) in front of From tells Agenda 
to add From as a child of MAIN. 

A category specification that starts without a category character is 
added as a child of the current category specified by the File Transfer 
Import command. (See Chapter 23 in the User's Guide.) 

Date categories 

By default. Agenda assumes all dates are in the format MM/DD/YY. 
Dates in a different format must be preceded with a date format tag 
that identifies the format. (See "Date Format Tags" earlier in this 
chapter.) On import. Agenda discards any information that cannot 
be interpreted as date information in the current format. 

Date categories can be created using {C} and {.} tags. However, 
Agenda also supports an older set of category commands for creating 
Agenda-defined date categories. These tags are: 


Tag Meaning 

{D} Done date 

{E} Entry date 

{W} When date 
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When any of these tags is used to create a date category, the date 
value immediately follows and concludes the date specification. A 
date specified by any of these tags does not end with the category-end 
tag {.}. 

For example, the following line adds a When date of 11/12/90: 
{WJll/12/90 

The following example shows how the same date category specifica¬ 
tion looks using {C} and {.} tags: 

{C}\When@ ! 11/12/90 

Escape character 

An escape character is a special character that tells Agenda to inter¬ 
pret the immediately following character as a text character. This is 
necessary whenever a category includes one of the category 
characters as a text character. The escape character in structured files 
is the percent sign (%). 

For example, if a category includes the number sign (#) in its text, the 
number sign must be preceded with the escape character ( %#) so 
that Agenda imports the number sign as text. Without the immedi¬ 
ately preceding escape character (%), Agenda interprets the number 
sign as the first character in the numeric category character. 

The following guidelines apply to the use of escape characters in cate¬ 
gory specifications: 

• The escape character must immediately precede the special char¬ 
acter to which it applies. There cannot be a space between the 
escape character and the character. 

• Each category character to be imported as text requires its own 
escape character. For example, if two slashes in a row (/ /) are to 
be imported as text, an escape character must precede each slash 
character, for example: 

%/%/ 

• If the category includes the percent sign (%) as a text character, the 
category specification must include two percent signs in a row: 

%% 
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Figure B-6 shows how category tags define categories. 


{C}\From\ Lynne George %/ MCI ID: 123-4567U 
{C}\When® \ Mon November 19,1990 9:24am GMTU 


Figure B-6 Sample category tags 


Figure B-6 defines two categories. Because each {C} specification 
begins with a backslash (\), the new categories are added as children 
of MAIN when they are imported into Agenda. The first {C} defines 
a From category, and makes the category Lynne George (along with 
her MCI ID) a child of From. 

The second {C} defines a When date of Mon November 19,1990. The 
date category characters (@ I) apply to the When category, and indi¬ 
cate that When is the parent category. The next value in the category 
specification is the date. If this When category is imported with an 
item. Agenda uses the date to assign the item to the When category. 
If the When category is not imported with an item, Agenda ignores 
the date value. 


Item Tags 


Item tags create an item and its associated categories and note. The 
following tags create an item: 


Tag Meaning 

{1} Beginning of an item specification (the item and associated categories, 
notes, and dates) 

{T} Beginning of the item text 

{!} End of an item specification 


Each {1} begins a new item. The item ends with a 

{!} tag. Tags between {1} and {!} add other elements to the item: 

• The {T} tag begins the item text 

• Category tags assign the item to the specified categories 

• Note tags {N} or {O} add a note to the item 
Category and note tags are discussed earlier in this chapter. 
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fT) specifies the item text. On import, Agenda ends the item text 
when it encounters another structured file tag. In Agenda, the item 
text can be a maximum of 350 characters in length. 

Caution If {T} identifies item text that is longer than this maximum, 
Agenda makes the first 350 characters into the item and 
ignores the remaining characters. 

When you use the File Transfer Import command, you can specify 
whether Agenda should import any of the following information 
from item specifications in the structured file: 

• Items and notes 

• Category assignments (assignment of items to existing categories) 

• New categories created in item specifications 

You also can specify the category to which imported items are 
assigned. For more information, see Chapter 23 in the User's Guide. 

Figure B-7 shows how sample item tags define an item. 


{STF}11 /02/90;12:21:08;002 
{ 1 } 

{TjFriday Lunch Canceled 
{C}\From\LeeX |.) 

{C}\Entry@ I Fri Nov 2,1990 9:23am GMT{.} 

{C}\Mail\E-Mail{.} 

{N}Rescheduled meeting Mon Nov 5, at 9am. 

(!) 

{II 

{Tj Attention Book Fans 
{C}\From\MartyV {.} 

{C}\Entry@ ! Fri Nov 2,1990 11:17am GMT{.} 

{C}\Mail\E-Mail{.} 

{NIGala Re-Opening 

Au Claire Books announced it's reopening its downtown store on the week¬ 
end of Nov 10 (you may remember, they were burned out along with Stacy's 
a few months ago). 

Their flyer says they'll have poetry readings Sat and Sun from 1 to 3 in the 
afternoon, and balloons for the kids. New books upstairs, and an expanded 
used section downstairs. And, an expanded comfy chair section!! (And, as 
always, 5% of sales to the usual charitable causes, including the Homeless 
Coalition, the Literacy Campaign, etc.). 


Figure B-7 Sample item tags 
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What Structured 


A Simple 
Electronic Mail 
Example 


Figure B-7 contains information extracted from electronic mail. This 
sample constructs two items. The text for the first item is Friday 
Lunch Canceled. The second item is Attention Book Fans. Each item 
is assigned to the From and Mail categories, and is assigned an Entry 
date. All text after the (N} is a note for the item. Each item specifica¬ 
tion starts with {1} and ends with {!}. 


Files Look Like 


This section provides examples of structured files. The first struc¬ 
tured file is based on a simple example in Chapter 4. The remaining 
structured files in this section are generated by the definition files 
presented in Chapter 3. 

This section presents 

• A simple electronic mail example with text file, definition file, and 
resulting structured file 

• The sample structured files created for the examples in Chapter 3 


This example shows one way to convert text in a sample electronic 
mail memo into category and item text. Figure B-8 shows a text file 
that contains an electronic mail message to be converted. 


To: Jill 
From: Linda 

Subject: Your proposal 

Jill, I liked your proposal 

but I had a few questions, 

could we get together next Wednesday 

to talk about it? 


Figure B-8 Text file containing an electronic mail message to 
be converted 


Figure B-9 shows the definition file that converts the sample text file. 
This definition file can convert a text file containing one or more 
electronic mail messages. The definition file assumes that each new 
electronic mail message begins with the string To: at the start of a 
line. When it finds this string, the definition file executes @end to 
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save the current contents of item, note, and category buffers to the 
structured file. Then it then begins converting the electronic mail 
message by executing ©trim. It continues converting text lines until it 
finds another To: at the start of a line, at which point it executes 
©end, and then converts the new electronic mail message. When it 
reaches the end of the text file (END), the definition file executes 
©end and then terminates. 


♦Converting memo text using @append_item 

START ©equate("SPACE"," ") 

©equate{"PERSON”,"") 

©start() 

#Create To category ("To:" starts each memo in the file) 

" A To\:" @end{) 

@trim(" A To\:"$", N, "PERSON") 
@custom_category(PERSON, "To",) 

#Assign a person to the From category 

” A From\:" @trim(" A From\:", N, "PERSON") 

©custom_category(PERSON, "From",) 

#Add subject line to item buffer 

,,A Subject\: " @trim(" A ", "Subject\ : ", ,) 

@item2("$") 

@append_item(SPACE) 

♦Discard blank lines so "~To:"(NOT To:) won't match them 

,,A [ ] *$" ©equate ("blanks","") 

#Add each remaining line to item buffer 

" A ~To\:" @trim(" A [ N, "LINE") 

©append_item(LINE) 

© append_item(SPACE} 

END ©end() 


Figure B-9 Definition file to convert text files containing 
electronic mail messages 


The definition file shown in Figure B-9 converts the names Jill and 
Linda into categories and converts the remaining memo text into an 
item. When it converts the memo text, the structured file removes the 
leading spaces from the text. Figure B-10 shows the structured file 
created by this definition file. 


#Converting memo text using @append_item 

{STF}ll/26/90;19:43:34;002 

{ 1 } 

{TJYour proposal 

Jill, I liked your proposal but I had a few questions, could we get together 
next Wednesday to talk about it? 

{C}To\ JillU 
{C}From\ LindaU 
{!} 


Figure B-10 Resulting structured file 


When the structured file is imported into Agenda, To and From are 
added as categories under the category specified in the File Transfer 
Import command. The name Jill is added as a child of To and Linda 
is added as a child of From. The item, which consists of the text from 
the Subject line plus the four-line memo, is assigned to the categories 
Jill and Linda. 


This section shows the sample structured files developed for the 
examples in Chapter 3. That chapter presented the text file and defi¬ 
nition file to: 

• Convert electronic mail messages 

• Convert a table of information 

The resulting structured files for each example is shown below. 

Converting an electronic mail message 

Figure B-ll shows the structured file created when TXT2STF used the 
sample definition file to convert the sample electronic mail file pres¬ 
ented in Chapter 3. 
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#definition file for electronic mail 

{STF}05/24/90;13:59:54;002 

{ 1 } 

{T}Charting Seminar! 

{C}From\Susan AnthonyX 
{F} Public Relations 
U 

{C}\Entry® ! 11/08/90 15:12:04{.} 

{OJEMAIL5.EML 

W 


Figure B-ll Sample structured file for converted electronic 
mail 

Converting a table of information 

Figure B-12 shows the structured file created when TXT2STF used the 
sample definition file to convert the sample CD/Corporate Industry 
Participants report file presented in Chapter 3. Since the original 
report, and therefore the resulting structured file, is long. Figure B-12 
shows only the structured information for the first five companies in 
the report. 
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#Table-reading DEF file sample for CD/Corporate participant table 
{STFJ05/24/90;09:59:34;002 
{C}Industry\Food Processing\{.} 

U) 

{T}Sara Lee Corp 
{QIncome #! 410,492{.) 

{QSales# ! 11,717,6781.} 

{C}FYE@! 7%/01%/89{.} 

{C}Company\{.} 

{C}Rank ! 1{.} 

{!} 

{ 1 } 

{TJConagra Inc 

{C}Income # ! 197,878{.} 

(QSales#! 11,340,414{.} 

{C}FYE@! 5%/28%/89{.} 

{C}Company\{.} 

{C}Rank! 2{.) 

{!} 

{ 1 } 

{T1IBP Inc 

{QIncome # ! 62,328{.} 

{CjSales#! 9,066,101 {.} 

{C}FYE@! 12%/31%/88{.} 

{QCompany \ {.} 

(C)Rank I 3U 

{!} 

{ 1 } 

{T}Archer Daniels Midland Co 
{Cllncome # ! 424,673{.} 

{QSales#! 7,928,836{.} 

{C}FYE@! 6%/30%/89{.) 

{C}Company\{.} 

{QRank! 4{.} 

{!} 

{ 1 } 

{T} Borden Inc 
{CJIncome#! 311,882{.} 

{QSales# ! 7,243,526{.} 

{C}FYE@ ! 12%/31%/88{.} 

{C}Company\{.} 

{ClRank! 5{.} 

{!} 


Figure B-12 Sample structured file for converted 

CD/Corporate Industry Participants report 



Appendix C 
Quick Reference 


Patterns 


Match-Control 

Characters 


This Quick Reference provides information about the patterns and 
commands you can include in definition files. 


To specify a pattern, you can 

• Type the text string itself 

• Include match-control characters in the pattern 

• Use special patterns START and END 

Use the following match-control characters to write patterns that can 
match a varied set of text strings in the input line. 


Match-Control Character 

Description 

Asterisk (*) 

Matches zero or more occurrences of the preceding 
pattern character 

Backslash (\) 

Specifies that the immediately following character 
in a pattern is a text character and not a match- 
control character 

Brackets ([ ]) 

Specifies a range or group of characters, and 
matches any single text character specified in the 
range or group 


continued 
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C-2 Quick Reference 


Special Patterns 


Match-Control Character 

Description 

Caret ( A ) 

As the first character in a pattern, causes the pat¬ 
tern to match the corresponding text only when it 
occurs at the beginning of a text line 


As the first character in a pair of brackets ([ ]), 
caret ( A ) negates the range or group specified in 
the brackets ([ ]) 

Colon a (:a) 

Matches any single uppercase or lowercase alpha¬ 
betic text character 

Colon d (:d) 

Matches any single numeric text character from 0 
through 9 

Colon n (:n) 

Matches any single alphabetic or numeric text 
character 

Colon space (: ) 

Matches a single space or control character in the 
text file 

Dollar sign ($) 

As the last character of a pattern, causes the pat¬ 
tern to match the corresponding text string only 
when it occurs at the end of a text line 

Parentheses () 

Groups pattern characters into a string so you can 
apply a match-control character to the string 

Period (.) 

Matches any single character in the text file (except 
a carriage return or linefeed character) 

Plus (+) 

Matches one or more occurrences of the immedi¬ 
ately preceding pattern character 

Tilde (~) 

Matches any text string that is not the pattern 

Vertical bar ( !) 

Matches one pattern or another (performs a logical 
OR) 

You can use the following two special patterns in definition file 
statements. 

Pattern Used for 


START Statements you want to execute only when TXT2STF starts process¬ 
ing the text file 

END Statements you want to execute only when TXT2STF finishes pro¬ 
cessing the text file 
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Definition File Commands 


The following pages describe 

• Syntax for definition file commands 

• Predefined variables you can use as command arguments 


Command Syntax This section provides the syntax for definition file commands. 

Note You can include spaces after the commas that separate argu¬ 
ments. If you omit an optional argument, you must include 
the comma that precedes the argument only if the comma 
precedes the brackets ([ ]) in command syntax. 


Command 

Description 

©appendi" variable-name",string) 

Adds a string to the end of the current contents of the vari¬ 
able 

@appenditem(sfring[,N]) 

Adds a string to the end of the current item 

@append_note(sfring) 

Adds a string to the end of the current note 

©category (separator-pattern, [paren f],[" type "]) 

Creates one or more categories from the text line and can 
make them children of a specified parent category 

©category_note(termination-pattern) 

Creates a category note and assigns it to the category created 
by the most recently executed ©category or ©customcate- 


S or Y 

©category _note_file(/i7e-«fl me) 

Identifies the external note file for the current category 

@custom_category (category, [paren t ] ,["type'']) 

Creates a category from text that you specify and can make 
the category a child of a specified parent category 

©dat e(category[,value]) 

Creates assignments to date categories; assumes date format 
MM/DD/YY 


continued 
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Command 

Description 

©date format( format-number) 

Indicates the format of dates and times in the 
structured file by specifying a format number (for¬ 
mats 1-6 use 24-hour time; 7-12 use 12-hour time): 

1 and 7 = MM/DD/YY 

2 and 8 = DD/MM/YY 

3 and 9 = DD.MM.YY 

4 and 10 = YY-MM-DD 

5 and 11 = DD-MMM 

6 and 12 = DD-MMM-YY 

@end() 

Copies the current contents of item, note, and cate¬ 
gory buffers to the structured file, and then ini¬ 
tializes the buffers 

@equate(' 'variable-name"'pattern ") 

Stores a pattern or a text string in a variable 

@grab(separator-pa ttern,field-n u mber,"variable-name" 

[,field-number,"variable-name",...]) 

Divides the current text line into several values 
and puts one or more of the resulting value into 
variables; leaves the text line intact in memory 

@itevi\{.termination-pattern,total-length,[N ]) 

Creates an item using text in the text file; is the 
Release 1.0 alternative to @item2 

@item2 (termination-pattern [,max-length] [,N]) 
or 

@item2(max-length[,N]) 

Creates an item using text in the text file; is the 
Release 2.0 alternative to ©item 

®make_externa\_note(termination-pattern,[ "directory "]) 

Creates an external note file and copies text from 
the text file into the note file; on import the note 
file is added as an item note 

@note(termination-pattern ) 

Creates a item note and assigns it to the current 
item 

@r\oteJi\e(file-name) 

Identifies the external note file for the current item 

@numeTic(category[,value]) 

Creates assignments to numeric categories 

@repla ce(search-pattern,replacement-string,[number]) 

Replaces the specified number of occurrences of 
the string identified by search-pattern with the 
replacement string 

©reset (replacemen t-string) 

Replaces the current text line in memory with the 
specified string 

©set ("variable-name") 

Stores the current text line in the specified variable 


continued 
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Command 

Description 

@s)dp(separator-pattern,field-number ) 

Divides the text line into values and then 
deletes one of the resulting values from the 
text line 

@skip_lines(termination-point) 

Skips over the number of text lines you spec¬ 
ify 

©startO 

Initializes the item, note, and category buffers 
TXT2STF uses to hold converted information 

@strip(strip-pattern,number ) 

Deletes one or more occurrences of a specified 
string from the text line 

@tab\e{separator-pattern,termination-pattern,col-number "type” 
[, col-number,"type ",...]) 

Makes items and categories from a table in 
the text file, using separator-pattern to divide 
the text into table columns 

©tximistart-pattern,end-pattern,[N\[,"variable-name"]) 

Deletes all the text between one string and 
another, and can place the deleted text in a 
variable 

@xmindexed(category,value) 

Creates assignments to unindexed categories 


Predefined You can use these predefined variables as arguments in definition file 

Variables commands. 


Variable 

Represents 

FILENAME 

The name of the current text file 

EOF 

End-of-file; used for specifying a termination point in com¬ 
mands 

CR 

Carriage return; used for adding the combination of carriage 
return (ASCII decimal 13) and linefeed (ACII decimal 10) to 
text 

D, E, and W 

Done date. Entry date, and When date, respectively 



Appendix D 
Error Messages 


Error messages provide information about problems that TXT2STF 
encounters while converting a text file. This appendix describes the 
error messages that you may see when working with TXT2STF. 


In this Appendix 


This appendix provides 

• Information about TXT2STF error messages 

• A description of each error message, with possible ways to correct 
the current problem 


About Error Messages 


Error messages notify you when one or more problems occur in con¬ 
verting a text file and give you a starting place for locating the prob¬ 
lem. Each TXT2STF error message starts with an identifying number, 
followed by a phrase that describes the situation that caused 
TXT2STF to display an error message. 

TXT2STF error messages can identify: 

• Errors in how a definition file statement is composed 

For example, the statement may begin with an invalid pattern or 
might include commands that do not comply with command syn¬ 
tax. 

* Errors that arise when TXT2STF uses the definition file 


D-1 
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For example, a statement may need to use the contents of a vari¬ 
able before any text is copied into the variable. 

• Errors that relate to your computer or its resources 

For example, your computer may run out of memory while 
TXT2STF is still converting a text file. 

If errors occur when you use a definition file, TXT2STF stops execut¬ 
ing either the command or the statement where the error occurs and 
displays the error message with as much information as possible 
about the current error. TXT2STF then resumes converting the file, 
after first skipping over the command or statement where the error 
occurred. 

If it skips over a command, TXT2STF lists the command that caused 
the problem when it displays the error message. If it skips over an 
entire statement, TXT2STF lists the current command, current text 
line, and the commands already executed in the statement when it 
displays the error message. 

To see more information about your errors, use the debugging option 
/A when you run TXT2STF. Also, redirect TXT2STF messages to a 
file so you can view them later. (See Chapter 7.) 


Error Messages and Descriptions 


The remainder of this appendix lists TXT2STF error messages and 
provides possible ways to correct the problem identified by each 
error message. Error messages are listed by error number. 

0 The end of the definition file was reached before the end of a 
command 

The definition file ends before expected. The current command is 
probably missing the closing (righthand) parenthesis. 

1 The current statement has an invalid format 

Make sure the current statement begins with a pattern and includes 
at least one command to convert text. Make sure that commands 
begin with the at (@) character and end with an argument list 
enclosed in parentheses. Also make sure that each pattern is enclosed 
in a pair of double quotation marks (" "). 
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2 An unrecognized command is in the definition file 

Make sure that all commands in the definition file begin with an 
at (@) character and are spelled correctly. 

3 An argument for the command is not recognizable 

Make sure that all arguments in the command are in the correct posi¬ 
tion and that all required commas are included in the command when 
optional arguments are omitted. Make sure that each argument is the 
right type. For example, if the syntax specifies that an argument can 
only be a numeric constant, make sure you have specified a numeric 
constant. Make sure that each string constant (including file name 
string and variable name string constants), pattern constant, and type 
constant is enclosed in a pair of double quotation marks (" "). Also 
make sure that each numeric constant, logical constant, and variable 
is not enclosed in double quotation marks (" "). 

4 There is not enough memory to execute this sequence of 
commands 

Your computer ran out of memory while TXT2STF was converting a 
text file. It is possible that you are currently running a software prod¬ 
uct that uses memory. Try to free this memory so that TXT2STF can 
use it, as follows: 

• You may have temporarily exited to the operating system from a 
software product. 

To free memory, return to the product (typically you type exit 
and press ENTER) and then exit completely from the product. 

• You may have run a product that stays resident in memory after 
executing, such as Lotus Express™. 

To free memory, use the key combination defined for this purpose 
(for Express, press the key combination alt-shift-end) or restart 
your computer without running any of products that remain in 
memory after use. 

If none of the above strategies free enough memory, see if you can 
shorten the statement so that it will need less memory to execute. It is 
possible that your computer does not have sufficient memory 
installed to run the definition file; contact computer support person¬ 
nel at your site if necessary. 



5 There is not enough memory to define another pattern 

There are more than 20 patterns currently defined in memory. The 
pattern that begins a statement remains defined in memory through¬ 
out the execution of the statement. Patterns that are used as argu¬ 
ments in commands are defined in memory only while the command 
is being executed. When the next command in a statement starts 
executing, the patterns for the previous command are removed from 
memory and the patterns for the current command are defined in 
memory. 

6 Bad pattern in the command 

Make sure that each pattern in the command is enclosed in a pair of 
double quotation marks (" "). Make sure that you used the correct 
match-control characters. Make sure the command does not include 
special patterns START or END; these commands can only begin 
statements. Make sure that all arguments are in the correct position. 
Make sure the command includes the correct number of arguments. 

7 Not enough arguments were supplied for the command 

Make sure that all arguments in the command are specified in the 
correct position and that all required commas are included for 
optional arguments that are omitted. Make sure the argument list 
does not include a closing parenthesis in the wrong location. 

8 Too many arguments were supplied for the command 

Make sure that the command includes only allowed arguments and 
that the command does not include non-required commas for 
optional arguments that are omitted. 

9 Command or data line too long 

The current text line can be a maximum of 512 characters in length. 

10 The variable specified in the command line does not exist 

The command specifies a variable that does not yet contain text, so it 
does not exist. Reorganize the statements in the definition file so that 
the statement that places information into the variable executes 
before the current statement. To review the order in which TXT2STF 
executes definition file statements, see "How TXT2STF Processes Each 
Text Line" in Chapter 2. 
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11 The variable name specified in the command line is too long 

A variable name can be up to 32 characters in length. Make sure that 
the variable name is spelled correctly. If the current argument must 
be a variable name string constant, make sure the variable is enclosed 
in a pair of double quotation marks (" ”)- If the argument is simply a 
variable, make sure the variable name is not enclosed in quotation 
marks. Make sure that all arguments in the command are specified in 
the correct position and that all required commas are included for 
optional arguments that are omitted. Make sure that non-required 
commas are not included for omitted optional arguments. 

12 A variable was given for an argument that cannot be a variable 

The command includes a variable for an argument that cannot be a 
variable. Consult the command syntax for valid arguments. Make 
sure that all arguments in the command are specified in the correct 
position and that all required commas are included for optional argu¬ 
ments that are omitted. Make sure that non-required commas are not 
included for omitted optional arguments. 

13 A number was given for an argument which cannot be a 
number 

The command includes a numeric constant for an argument that can¬ 
not be a numeric constant. Consult the command syntax for valid 
arguments. If the number should be a string constant, enclose it in a 
pair of double quotation marks (" "). Make sure that all arguments in 
the command are specified in the correct position and that all required 
commas are included for optional arguments that are omitted. Make 
sure that non-required commas are not included for omitted optional 
arguments. 

14 Argument too long 

An argument in the command contains too many characters. Consult 
the command syntax for the correct length for arguments. Make sure 
that all arguments in the command are specified in the correct posi¬ 
tion and that all required commas are included for optional arguments 
that are omitted. Make sure that non-required commas are not 
included for omitted optional arguments. 

15 Missing, or) in command 

The command either is missing a required comma (,) or does not end 
in a closing (righthand) parenthesis. 



16 Variable is full 


The current variable contains 512 characters, which is the maximum 
number of characters a variable can contain. 

17 Wrong type supplied for an argument 

An argument in the current command is specified incorrectly. For 
example, the argument is supposed to be a numeric constant, but is 
currently a string constant. 

18 Unbalanced 0's 

A pattern includes a different number of open (lefthand) parentheses 
than closing (righthand) parentheses. Make sure each open parenthe¬ 
sis has a corresponding closing parenthesis. Also make sure each 
closing parenthesis closes an expression that starts with an open 
parenthesis. Inspect nested parentheses carefully for mismatched 
open and closing parentheses. 

19 Too many tildes (~) per subpattem 

A subpattern contains too many tilde characters (~). There can be a 
maximum of one tilde (—) in each subpattern defined 

• In a nesting level defined by a pair of parentheses 

• At the top level of the pattern, before an open parenthesis begins a 
nesting level 

For example, the pattern "~a~b" is incorrect but ~(ab) and ~a(~b) are 
correct. 

Each pattern on either side of a vertical bar (!) character defines a 
new subpattern at the current level. This means that the pattern 
"-Meeting ! -Seminar" is correct because each subpattern at the cur¬ 
rent level contains only one tilde (~). 

20 Pattern too big 

The pattern is too complicated. When TXT2STF tries to compile the 
pattern into an internal form, the pattern exceeds the capacity of 
TXT2STF to store it. Try to simplify the pattern. 

21 Too many classes 

An entire pattern can include up to eight different character class 
specifications. 
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22 No closing square bracket (]) 

An open bracket ([) in a pattern indicates the start of a range or 
group specification, but the specification does not end in a closed 
bracket (1). 

23 Bad colon(:) class 

There are only four match-control characters that begin with colons, 
colon a (:a), colon d (:d), colon n (:n), and colon space (: ). Make sure 
that each colon space (: ) combination includes a space after the 
colon. 

24 Too many ()'s 

The pattern includes too many levels of nested parentheses. A pat¬ 
tern can include up to 10 nesting levels. If you end one set of paren¬ 
theses before starting a second set, both parentheses are at the same 
level of nesting, and do not cause this error to occur. 

25 Carat ( A ) can only be the first character 

The carat ( A ) must be the first character in a pattern to match the 
pattern with a string at the start of a text line. For example, 
" A Hardware ! A Software" is invalid; the correct way to write this pat¬ 
tern is " A (Hardware ! Software)". 

26 Dollar sign ($) can only be the last character 

The dollar sign ($) must be the last character in a pattern to match the 
pattern with a string at the end of a text line. For example, 

"follows® ! below$" is invalid; the correct way to write this pattern is 
"(follows! below)$". 

27 Bad pattern 

TXT2STF cannot use the pattern because it contains invalid characters 
or some other error that invalidates it. 

28 One of the arguments for the command was empty 

It is possible that an argument in the current command either speci¬ 
fies an empty string, which consists of two double quotation 
marks ("") without any intervening space. In this case, correct the 
argument. Another possibility is that a variable does not contain text 
when TXT2STF attempts to use it. In this case, see the description for 
error message 10 for ways to correct the problem. 
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29 There is not enough memory to define another pattern 

Your computer ran out of memory while TXT2STF was converting a 
text file. See the possible solutions listed for error message 4. Also, 
see if you can eliminate any patterns from commands in the current 
statement. Look for commands that can be rewritten to use an 
argument other than a pattern. For example, see if @item2 can spec¬ 
ify where the item ends by using a total length parameter and not a 
pattern. 

30 Unexpected end of file 

The text file ends before expected. The current statement assumes 
that more text remains to be converted. Look at the command and 
make sure it specifies the correct arguments. Make sure the text file is 
complete, and has not been shortened (truncated). 

31 File has an invalid format 

The text file is not an ASCII text file. It is possible that it contains 
hidden characters added by the product originally used to create the 
file. Use that product to create a copy of the file that contains only 
ASCII characters. Then, convert that copy of the file. 

32 Out of memory 

Your computer ran out of memory while TXT2STF was loading a 
statement. It is possible that the statement is too big. It also is possi¬ 
ble that there is not enough memory to execute this sequence of com¬ 
mands; see the possible solutions listed for error message 4. 

33 Current text line is split because it's too long 

The current line contains more than 512 characters and so TXT2STF 
must split the line to process it. TXT2STF processes the first 512 
characters as one text line, and the remaining characters as another 
text line. If the current statement ends when TXT2STF is only part¬ 
way through this second text line, TXT2STF discards the text line and 
continues to the next unprocessed text line in the text file. 

Unprocessed characters on the discarded second text line are never 
processed. 

34 The exclamation point (!) is not a valid pattern character 

The pattern contains an exclamation point (!), which is not a valid 
match-control character in a pattern. To create a negative pattern, use 
the tilde (~) and not the exclamation point (!). To search for the excla¬ 
mation point (!) as a regular text character, place a backslash (\) 
immediately before the exclamation point (!). 



Index 


Symbols and special characters 
See also Category characters; 
Match-control characters 
asterisk (*) 3-5,4-4,4-5,4-17, C-l 
at (@) 2-3,3-5,5-7 
backslash (\) 4-4,4-6,5-3, 5-8 to 
5-10,6-5 

brackets ([ ]) 4-5 to 4-8,5-7, D-6, 
D-7 

caret ( A ) 1-8,4-4, 4-8 to 4-9 
colon {:) 1-8,4-5,4-10 
comma (,) 5-7,5-8,5-21,6-5 
dollar sign ($) 3-7,4-5,4-11,4-16 
to 4-18 

double note (D 3-10 
double quotation marks (") 2-3, 
4-2,5-7,5-8 to 5-10,5-17 
ellipses (...) 5-7 
escape (%) B-13 to B-14 
exclamation point (!) A-3, D-8 
hyphen (-) 4-7,6-3 
note (B) 1-14,3-10 
number (#) 2-5 

parentheses 4-11,5-8, A-3, D-6 to 
D-7 

percent (%) B-13 to B-14 
period (.) 3-5,4-5,4-12, C-2 
plus (+) 3-15,4-12 to 4-13,4-17, 
C-2 

semicolon (;) B-5 to B-6 

single quotation mark (') 4-2,5-7 

slash (/) 6-3 

space () 5-20,5-21 

tilde (~) 4-4, 4-14 

vertical bar (I) D-6 

A 

Actions See Definition file 
commands 

Adding See also Appending; 
Converting 

definition file patterns to state¬ 
ments 1-7 to 1-9,4-2 to 4-3 
notes to categories 3-7 to 3-4,5-22 
to 5-25, B-8 to B-9 


notes to items 3-9 to 3-10,5-43 to 
5-48, B-9 to B-10 
statements to definition files 2-3 
to 2-5, 7-12 to 7-13 
/A debugging option 7-3, D-2 
Analyzing text files 1-5 to 1-7,2-2 
Anchoring negative patterns 4-13, 

4- 17 to 4-18,7-9 
©append 

defined 5-6, 5-13 to 5-14 
example 5-9,5-54 
Appending See also Adding 
strings to items 5-4, 5-14 to 5-16 
strings to notes 5-5, 5-17 to 5-19 
strings to variables 5-6, 5-13 to 

5- 14 

text to elements 7-11 to 7-12 
@append_item 

defined 5-4, 5-14 to 5-16 
example 5-8 

@append_note 5-5, 5-17 to 5-19 
Arguments 

defined 5-7 to 5-8 
empty D-7 
invalid D-5 
length of D-5 

optional 5-7,5-8,5-14,5-65 
parentheses in 5-6, 5-8, D-6 
patterns as 4-2, 4-14 to 4-19, 5-10, 
5-22 

syntax 5-8 
types 5-8 to 5-11 
unrecognized D-3 
variables 5-9, 5-11 to 5-13 
wrong number of D-4 
ASCII See also Text files 

characters 4-8,4-10,4-18 to 4-19 
decimal codes 6-5 
Assigning 

dates to date categories 5-4,5-28 
to 5-29,5-62 

dates to items 5-53 to 5-54 
items to categories 1-11,3-11 to 
3-16,5-19, 5-25 to 5-29, 

5-49 to 5-50,5-67 to 5-68, B-ll 
items to numeric categories 5-26, 
5-49 to 5-50 


items to unindexed categories 
5-67 to 5-68 

notes to categories 5-22 to 5-25 
notes to items 5-5,5-43 to 5-48 
patterns to variables 7-9 
values to variables 5-34 to 5-36 
Assignments, specifying 6-7 
Asterisk (*) 

defined 3-5,4-4,4-5, C-l 
plus {+) compared with 4-5,4-12 
to 4-13,4-17 
At sign (@) 2-5,3-5,5-7 
At-vertical bar (@ I) B-ll to B-12 

B 

Backslash (\) 

in Agenda 1.0 2-4 
in arguments 5-8,5-10 
category names separated with 
5-26 

defined 4-4,4-6 

in definition file commands 5-3 
exclamation point (!) 
preceding D-8 

indicating standard category 
B-ll 

preceding statements A-2 
as separator character 6-8 
Brackets ([ ]) 

in Agenda 2.0 A-3 
defined 4-5 to 4-8 
missing from pattern D-6 
typographical convention 5-7 
Buffers See Memory buffers 
Building 

category hierarchy 1-9 to 1-10, 

5- 25 to 5-27,5-62 to 5-64,6-6 to 

6- 7, B-2 

structured files 2-10 to 2-11 
Bundling information in memory 
2-6,2-11 

C 

Caret ( A ) 

in Agenda 2.0 A-3 


index-1 
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anchoring negative patterns with 
4-17 to 4-18 

defined 1-8,4-4,4-8 to 4-9, C-2 
matching patterns 3-5,4-16 to 
4-18 

position in pattern D-7 
Carriage return See also CR 
variable 
matching 4-8 

as separator character 2-8,6-3, 

6- 5 

as variable value 5-13 
Case 4-2,4-16, 6-2 
Categories 

analyzing text for conversion 2-2 
assignment to 6-7 
copying to structured files 5-32 
to 5-33 

date 5-28 to 5-29,5-62, B-ll to 
B-13 

debugging 7-4 to 7-5 
default type 5-20 
definition file statements con¬ 
verting 3-6 to 3-9 
exclusive 5-10, B-ll to B-12 
importing 3-10,6-6 to 6-7,7-4 to 

7- 5, B-ll to B-12 

items assigned to 1-11,3-11 to 

3-16,5-4,5-19, 5-25 to 5-29, 

B-ll 

names 5-20,5-28,5-49,5-67 to 
5-68 

notes assigned to 3-7 to 3-9,5-22 
to 5-25, B-8 to B-9 
numeric 5-26,5-49 to 5-50 
removing text from 5-56 to 5-59 
saving with @end 3-14 
single 7-10 to 7-11 
standard 5-10,5-62 
structured file tag converting 
B-2, B-10 to B-12 
tables converted to 3-10 to 3-16, 
5-5, 5-62 to 5-64 

tagging 2-11, 7-4 to 7-5, B-3, B-10 
to B-12 

text converted to 1-9 to 1-10,3-6 
to 3-8,5-19 to 5-22,5-25 to 5-27 
types 5-10,5-20,5-62 
unindexed 5-4,5-62, 5-67 to 5-68 
values in buffers 2-11 
©category 

in Agenda 2.0 A-5 
defined 5-4, 5-19 to 5-22 
example 5-10, 5-23, 5-26 to 5-27 
Category buffers 

building items in 2-10 to 2-11 
copying contents to structured 
file 5-32 to 5-33 


initializing 5-3, 5-59 to 5-60 
Category characters B-ll to B-12 
Category commands, defined 5-3 to 
5-4 

Category hierarchy 

building 1-9 to 1-10,5-25 to 5-27, 
5-62 to 5-64, B-2 
importing 1-4,5-36, 6-6 to 6-7, 
B-12 

Category names 
@category_note 

defined 5-5, 5-22 to 5-24 
example 5-61,5-66 
@category_note_file 5-5,5-24 to 
5-25 

Category notes 

converting text to 3-7 to 3-9,5-5, 
5-22 to 5-25 

creating with note tags B-8 to B-9 
Category tags 7-4 to 7-5, B-3, B-10 
to B-14 

{C} category tag B-10 to B-14 
in Agenda 2.0 A-6 
building category hierarchy with 
7-4to 7-5, B-12 
defined B-4, B-10 to B-14 
Character classes 
matching 4-18 to 4-19 
maximum number per 
command A-3 
number allowed D-6 
Characters See also Text; Text lines 
class specifications 4-18 to 4-19 
copying to item buffers 
groups 4-7,4-11,4-18 to 4-19 
literal 4-5 

matching 3-5,4-4,4-9 to 4-10, 

4- 12 to 4-13,4-18 to 4-19 
ranges 4-5 to 4-8,4-18 to 4-19 
searching for with TXT2STF 4-18 

to 4-19 

Child categories See also Categories; 
Category hierarchy 
category characters indicating 
B-12 

tables converted to 3-11 to 3-16, 

5- 62 to 5-64 

text converted to 1-9,3-7 to 3-9, 
5-19 to 5-22,5-25 to 5-27 
Classes See Character classes 
Clearing memory 2-11,3-15 
Colon {:) 1-8,3-5,4-4,4-17 
Colon a (:a) 

in Agenda 2.0 A-3 
defined 4-4, 4-9, C-2 
matching alphabetic characters 
with 4-18 to 4-19 


Colon d (:d) 

in Agenda 2.0 A-3 
defined 4-4,4-10, C-2 
matching numeric characters 
with 4-18 to 4-19 
Colon n (:n) 

in Agenda 2.0 A-3 
defined 4-4,4-10, C-2 
matching characters with 4-18 to 
4-19 

Colon space (:) 

defined 4-5,4-10, C-2 
matching control characters with 
4-18 to 4-19 
Columns See Tables 
Comma (,) 5-7,5-8,5-21,6-5, D-5 
Command names See Definition file 
commands, syntax 
Commands See Definition file com¬ 
mands 
Comments 

in definition files 2-5 
in structured files B-6 
Comment tag {S} B-6 
Comparing patterns and text See 
Matching 

Constants in arguments 5-8 to 5-10 
Control characters, matching 4-5, 

4- 10,4-18 to 4-19 

Control commands, defined 5-3 to 

5- 4 

Controlling formats See Formats 
Conversion 

debugging 7-7 to 7-8, D-l to D-2 
file options 6-2 to 6-5 
terminating 5-22 

/C conversion option 4-2,4-16,6-2 
to 6-3, A-2 

Converting See also Converting text; 
Importing 

ASCII text files 1-1,3-10 to 3-11 
bundled text 2-5 to 2-7 
date formats 5-29 to 5-31,5-51 
with definition file statements 
3-4 

electronic mail files 1-13 to 1-15, 
2-2,3-2 to 3-10, B-16 to B-19 
multiple text files 6-6 
options for 6-2 to 6-3 
paragraphs to items 1-2,6-3 
reports 3-10 to 3-16 
tables 3-10 to 3-16,5-62 to 5-64, 
B-19 to B-20 
text layout 7-11 to 7-12 
When dates 1-8 to 1-9 
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Converting text 

to categories 1-9 to 1-10,3-6 to 

3-8, 5-19 to 5-22,5-25 to 5-27, 
B-5 to B-16 

to category notes 3-7 to 3-9,5-22 
to 5-25 

to child categories 3-7 to 3-9 
with definition file commands 

2- 8,4-2 

identifying text lines for 4-15 
to item notes 2-9, 5-45 to 5-47 
to items 1-10 to 1-11,3-9,3-10, 
5-37 to 5-43,5-54 
to multiple items 7-13 to 7-14 
to notes 1-10 to 1-11,2-10 to 2-11, 

3- 7 to 3-9, 5-22 to 5-25,5-43 to 
5-49 

by pattern 4-14 to 4-19 
to single element 7-10 to 7-11 
Converting text files 

in Agenda 2.0 A-l to A-2 
defined 1-11 to 1-15,2-7 to 2-13, 
5-37 to 5-43 
Copying 

characters to item buffers 5-40 to 
5-43 

contents of buffers 5-32 to 5-33, 
5-59 to 5-60, B-3 
to structured files 2-11,5-19 to 
5-22,5-32 to 5-33,5-62 to 5-64 
text lines 2-8 to 2-9,5-37 to 5-39 
text to note files 5-43 to 5-45 
text to variables 1-9 to 1-10 
Creating See also Adding; Convert¬ 
ing 

category hierarchy 1-9 to 1-10, 
5-25 to 5-27,5-62 to 5-64, B-2, 
B-12 

definition file patterns 1-7 to 1-9, 

4- 2 to 4-3 

definition files 1-5,2-1 to 2-7 
entry dates 3-5 to 3-6 
notes with tags B-2, B-8 to B-9 
Structured files B-3 
variables 5-3, 5-13 to 5-14 
CR variable 5-13 
@custom_category 
in Agenda 2.0 A-5 
defined 5-4, 5-25 to 5-27 
example 5-15,5-21,5-33 to 5-34 

D 

©date 

in Agenda 2.0 A-5 
defined 3-6, 5-4, 5-28 to 5-29 
example 5-31,5-51 


Date categories 

creating with category tags B-ll 
to B-13 

defined 5-28 to 5-29 
example 3-14 

Date commands, defined 5-3 to 5-4 
@date_format 5-4, 5-29 to 5-31, B-6 
Date format tags B-6 to B-8 
{D} date tag B-12 to B-13 
Dates 

as arguments 5-8 
assigning to date categories 5-4, 

5-28 to 5-29,5-62 
assigning to items 5-53 to 5-54 
default format 5-31, B-6 
Done 5-13, B-12 to B-13 
Entry 3-4 

formatting 5-28 to 5-31,5-51 
predefined variables for 5-13, C-5 
tags B-6 to B-8 
values 3-15, 5-28 to 5-29 
When 1-8 to 1-9,5-13, B-12 to 
B-13 

/D conversion option 
in Agenda 2.0 A-2 
defined 6-2,6-3 to 6-4 
specifying files with 7-2 
Debugging 

in Agenda 2.0 A-2 
conversion 7-7 to 7-8 
defined 7-1 to 7-2 
definition file patterns 7-5 to 7-9, 
D-4, D-7 

definition file commands 7-7, D-3 
toD-5 

definition files 6-4 to 6-5,7-1 to 
7-3 

examining results of 7-4 
options, list of 7-3,4-15 
text line format 7-7 to 7-8 
Default 

category type 5-20 
date format 5-31, B-6 
items as 1-2 

separator characters 6-5 
Definition file commands 
in Agenda 2.0 A-4 to A-5 
arguments in 5-7 to 5-11 
converting text with 2-8,4-2 
debugging 7-7, D-3 to D-5 
defined 2-3,5-1 to 5-3 
displaying during execution 7-7 
to 7-8 

from earlier releases 5-3 
executing 3-6, 5-2,7-10 
last in file 5-32 to 5-33 
line length D-4 


pattern arguments in 4-2,4-14 to 

4- 19,5-10,5-22 

separating from patterns 2-3 to 
2-4 

specifying variables in 5-11 to 

5- 13 

summary list of 5-4 to 5-6, C-3 to 
C-5 

syntax 2-5 to 2-7,5-6 to 5-8 
terminating 5-13, 5-57 to 5-59 
unrecognized D-3 
writing 1-7 to 1-9 
Definition file commands, defined 
©append 5-6,5-13 to 5-14 
@append_item 5-4, 5-14 to 5-16 
@append_note 5-5, 5-17 to 5-19 
©category 5-4, 5-19 to 5-22 
@category_note 5-5,5-22 to 5-24 
@category_note_file 5-5,5-24 to 
5-25 

@custom_category 5-4,5-25 to 
5-27 

©date 5-4,5-28 to 5-29 
@date_format 5-4, 5-29 to 5-31 
©end 2-5,5-4, 5-32 to 5-33 
©equate 5-6, 5-33 to 5-34 
©grab 5-6, 5-34 to 5-36 
©item 5-4, 5-37 to 5-40 
@item2 5-2,5-4, 5-40 to 5-43 
®make_extemal_note 5-5, 5-43 to 
5-45 

©note 5-5, 5-45 to 5-48 
@note_file 5-5,5-48 to 5-49 
©numeric 5-4,5-49 to 5-50 
©replace 5-5,5-51 
@reset 5-6,5-52 
©set 3-6,5-6,5-55 
©skip 3-6,5-2,5-5, 5-55 to 5-57 
@skip_lines 5-5,5-57 to 5-59 
©start 3-6, 5-4, 5-59 to 5-60 
©strip 5-5, 5-60 to 5-61 
@table 5-5, 5-62 to 5-64 
©trim 3-6,5-5,5-6,5-64 to 5-66 
©unindexed 5-4, 5-67 to 5-68 
Definition file patterns 
in Agenda 2.0 A-3 
as arguments 4-2,4-14 to 4-19, 
5-10,5-22 

assigning to variables 7-9 
beginning statements with 5-1 to 
5-3, 7-10 

caret < A ) in 3-5,4-17 to 4-18, D-7 
complicated D-6 
creating 1-7 to 1-9, 4-2 to 4-3 
debugging 7-5 to 7-9, D-4, D-7 
defined 2-3,4-1 to 4-2,4-14 to 
4-19 

dollar sign ($) in 4-16 to 4-18, D-7 
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general and specific 7-6 to 7-10 
locating elements with 7-10 to 
7-11 

match-control characters in 4-4 
matching to text lines 1-11 to 

1- 15,2-8,3-7 to 3-8,4-1 to 4-2, 
4-16 to 4-18 

negative 4-13,4-17 to 4-18,7-9 
nesting levels in 4-11 
separating from commands 2-3 
to 2-4 

special 4-2 to 4-3, C-2 
specifying 7-8 to 7-9, C.-1 to C-2 
statements beginning with 4-1 to 
4-2, 4-15, 7-8 to 7-10 
storing in variables 5-6 
strings compared with 4-16 to 

4- 18 

tilde (~) in D-6 
types 2-4 

variable name equated with 5-6, 

5- 33 to 5-34 
writing 7-8 to 7-9 

Definition files 

converting text files with 5-15 to 
5-16,5-21 to 5-22, 6-3 to 6-4 
creating 1-5,2-1 to 2-7 
debugging 6-4 to 6-5,7-1 to 7-3, 
D-2 

defined 1-2 to 1-3 
documenting 2-5 
naming 7-1 to 7-2 
running TXT2STF with 1-4,2-7 to 

2- 13, 6-1 to 6-2 
specifying 6-2 to 6-4, 7-2 
statements added to 2-3 to 2-5, 

7-12 to 7-13 
terminating 3-9 
Definition file statements 

adding to definition files 7-12 
in Agenda 1.0 2-4 
backslash (\) preceding A-2 
beginning with ©start 5-59 to 
5-60 

categories converted with 3-6 to 

3- 9 

debugging 7-7, D-2 to D-5 
defined 2-3 
documenting 2-5 
format errors in D-2 
grouping 7-14 

items converted with 7-13 to 7-14 
match-control characters in 3-5 
matching 7-6 to 7-7,7-10 
maximum length of 2-4 
ordering in file 1-11 to 1-15, 7-9 
to 7-10 


patterns added to 1-7 to 1-9, 4-2 
to 4-3 

START and END in 4-2 to 4-3, 
7-13, C-2 

starting with patterns 4-1 to 4-2, 

4- 15,7-10 

syntax 4-2,5-1 to 5-3 
writing 1-7 to 1-15,2-3 to 2-5 
Deleting 

strings from text lines 5-5, 5-60 to 

5- 61 

text 3-6,3-9,3-13,5-6, 5-64 to 5-66 
values from text lines 5-5, 5-55 to 
5-57 

Discarding text lines 5-57 to 5-59 
Displaying 

definition file commands 7-3 
text lines 7-3,7-7 to 7-8 
variables 7-8 

Dividing text lines into values 3-15, 
5-5,5-21, 5-34 to 5-36, 5-55 to 
5-57 

Documenting 

definition file statements 2-5 
structured files B-6 
Dollar sign ($) 
in Agenda 2.0 A-3 
defined 4-5, 4-11, C-2 
in definition file commands 5-20, 
5-41 

matching patterns with 3-7,4-16 
position in pattern D-7 
Done dates 5-13, B-12 to B-13 
DOS files and directories as argu¬ 
ments 5-9 

Double note symbol («R) 3-10 
Double quotation marks 
in arguments 5-7 
in patterns 2-3,4-2 
string constants in 5-8 to 5-10 
string value in 5-17 
D variable 5-13 

E 

{E} date tag B-4, B-12 to B-13 
Electronic mail files 1-13 to 1-15, 

2-2,3-2 to 3-10, B-16 to B-19 
Ellipses (...) 5-7 
Empty arguments D-7 
©end 

bundling information with 2-6, 
2-11 

copying buffer contents with 
5-59 to 5-60, B-3 
copying to structured file with 
5-19 to 5-22 

defined 2-5,5-4, 5-32 to 5-33 


END pattern with 4-3 
example 5-15,5-23 
grouping statements with 7-14 
Ending TXT2STF See 
Terminating 

End-of-file See EOF variable 
End-of-line character See Dollar 
sign ($) 

END pattern 4-2 to 4-3,7-13, C-2 
Entry dates 3-5 to 3-6,5-13, B-12 to 
B-13 

creating with tags B-12 to B-13 
EOF variable 
defined 3-9,5-13 
example 3-15,5-39,5-45,5-58 
©equate 

defined 5-6,5-33 to 5-34 
example 5-15,5-54 
Equating variable names with pat¬ 
terns 5-33 to 5-34 
Error messages 

in Agenda 2.0 A-l to A-2 
defined D-l to D-2 
storing in files 7-4 
Errors, types 7-5 to 7-8, D-l to D-2 
Escape character (%) B-13 to B-14 
E variable 5-13 
{!} item tag B-14 to B-16 
Exclamation point (!) A-3, D-8 
Exclusive categories B-ll to B-12 
Executing definition file commands 
See also Definition file com¬ 
mands 

External note files See Note files 

F 

File name string constant argu¬ 
ments 5-9 

FILENAME variable 
defined 3-9,5-12 
example 5-48 to 5-49 
Files 5-12 See also Definition files; 
Note files; Structured files; 
Text files 
end of D-8 
invalid format D-8 
Lotus PRN 1-1 

storing error messages in 7-4 
types of information in 2-2,2-6, 
7-13 to 7-14 

File Transfer Import command 1-3, 
3-10, 6-6 to 6-7, B-ll 
{F} note tag B-4, B-8 
Formats 

controlling 1-2 

debugging text lines 7-7 to 7-8 
default file 1-2 
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invalid file D-8 

Formatting See also Converting 
dates and times 5-28 to 5-31,5-51 
errors D-2 
text 2-2 

Formatting text files See 
Converting 

G 

{G} note tag B-4, B-8 to B-10 
General patterns See Definition file 
patterns 

©grab 5-6, 5-34 to 5-36 
Grouping 

characters 4-7,4-18 to 4-19 
statements 7-14 

H 

Header tag A-6, B-4 to B-6 
Hyphen (-) 4-7,6-3 


Importing 

categories 3-10, 6-6 to 6-7, B-ll 
category hierarchy 1-4,5-36, 6-6 
to 6-7, B-12 

items and notes 3-10,6-6 to 6-7 
structured files 3-10,6-6 to 6-7, 
7-4 to 7-5, A-6 

with structured file tags 2-11, 7-4 
to 7-5 

text files 1-2 
Information 

bundling in memory 2-6,2-11 
converting tabular 3-10 to 3-16, 
5-62 to 5-64, B-19 to B-20 
copying to structured files 2-11, 
5-19, to 5-22,5-32 to 5-33 
saving in ASCII files 3-10 to 3-11 
storing with TXT2STF 2-5 to 2-7 
types 2-2,2-6,7-13 to 7-14 
Initializing 

memory buffers 2-5 to 2-6,5-32 
to 5-33,5-59 to 5-60 
variables 5-3, 5-32 to 5-34 
Invalid arguments D-5 
©item 5-4, 5-37 to 5-40 
@item2 

converting with 5-29, 545 
defined 5-4,5-40 to 5-43 
storing characters in item buffers 
with 5-2 
Item buffers 

adding strings in 5-14 to 5-16 
building items in 2-10 to 2-11 


copying characters to 5-40 to 5-43 
copying contents to structured 
file 5-32 to 5-33, 5-59 to 5-60 
copying text lines to 5-37 to 5-39 
empty 5-19 

initializing 2-5 to 2-6,5-32 to 
5-34, 5-59 to 5-60 
maximum number of characters 
in 5-37 to 5-38 

Item commands, defined 5-3 to 5-4 
Item notes 1-10 to 1-11, 5-45 to 5-47, 
B-9 to B-10 

Items 

appending to strings 54, 5-14 to 
5-16 

appending text to 7-11 to 7-12 
as arguments 5-8 
assigning notes to 5-5,5-12, 543 
to 5-48 

assigning to categories 1-11,3-11 
to 3-16,5-19, 5-25 to 5-29, B-ll 
assigning to numeric categories 
549 to 5-50 

assigning to unindexed catego¬ 
ries 5-67 to 5-68 
building 2-10 to 2-11 
converting more than one 7-13 to 
7-14 

converting with tags B-2, B-14 to 
B-16 

copying to structured files 5-4, 
5-32 to 5-33,5-62 to 5-64 
date 5-53 to 5-54 
as defaults 1-2 
empty 2-11 

importing 3-10, 6-6 to 6-7 
initializing memory buffers for 

2- 5 to 2-6,5-32 to 5-33, 5-59 to 
5-60 

note files with 5-12,5-43 to 5-45, 
5-48 to 5-49 

paragraphs converted to 6-3 
removing text from 5-2, 5-56 to 
5-59 

single 7-10 to 7-11 
starting and ending 6-3 
stored in buffers 2-11 
tables converted to 3-10 to 3-16, 
5-62 to 5-64, B-19 to B-20 
tagging 2-11, B-14 to B-16 
text converted to 1-10 to 1-11, 

3- 9,3-10,5-37 to 5-43,5-54 
{!} item tag B-4, B-14 to B-16 

{1} item tag B-4, B-14 to B-16 
{T} item tag B-4, B-14 to B-16 
Item tags 2-11, B-4, B-14 to B-16 


K 

Keywords 5-6,5-7 

L 

Layout See Text 

/L debugging option 7-3,7-7 to 7-8 
Length of definition file statements 
2-4 

Line feeds 4-8^ 5-13 
Literal characters 4-5 
LM2STF1-1 

Logical constant arguments, 
defined 5-10 

Lotus 1-2-3 worksheet 3-11,5-62 
Lowercase See Case 

M 

@make_externaI_note 
in Agenda 2.0 A-5 
defined 5-43 to 545 
example 5-9 

Match-control characters 
asterisk (*) 3-5,4-4,4-7 
in Agenda 2.0 A-3 
at (@) 3-5,4-4,4-5 
backslash (\) 3-5,4-4,4-6 
brackets ([ ]) 3-5,4-4,4-6 
caret ( A ) 3-5,44,4-8 
colon (:) 3-5, 44, 4-9 to 4-10 
defined 4-4 

dollar sign (S) 4-4,4-11 
parentheses 4-4,4-11 
in patterns 4-2,4-16 to 4-18,5-10, 
7-8 to 7-9 
period (.) 3-5 
plus (+) 4-4,4-12 
summary list of C-l to C-2 
tilde R 4-4, 4-13,7-9 
vertical bar ( ! ) 4-5,4-14 
Matching 

beginning of text line 4-8 to 4-9, 

4-16 to 4-18 

characters 4-4 to 4-5,4-9 to 4-10, 

4-18 to 4-19 

definition file statements 7-6 to 
7-7,7-10 

end of line 4-11,4-16 
literal characters 4-5 
multiple occurrences of text 4-12 
to 4-13,4-17 
nested levels 4-11 
non-pattern characters 4-13,4-17 
to 4-18, 7-9 
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patterns to text 1-11 to 1-15,2-8, 

3- 7 to 3-8,4-1 to 4-2,4-14 to 

4- 19, 7-6 to 7-7 

single characters 4-9 to 4-10,4-12 
strings 4-11 

text 3-5,4-4,4-12 to 4-13 
text lines to patterns 1-8,2-8,5-2 
/M debugging option 4-15,7-3 
Memory- 

bundling information in 2-6,2-11 
clearing 2-11,3-15 
problems with 2-4 
reserving with ©start 3-6 
running out D-3 to D-4, D-8 
TXT2STF using 2-8 
Memory buffers 

category 2-10 to 2-11,5-32 to 5-33 

clearing 2-11,3-15 

copying contents of 5-32 to 5-33, 

5- 59 to 5-60, B-3 
initializing 2-5 to 2-6,5-3,5-4, 

5-32 to 5-33,5-59 to 5-60 
item 2-10 to 2-11,5-14 to 5-16, 
5-37 to 5-43 

note 5-14,5-17 to 5-19,5-32 to 
5-33, 5-41 

storing information in 2-11 
Mistakes See Errors 

N 

Negative patterns 4-13,4-17 to 4-18, 
7-9 

Nesting levels in patterns 4-11, D-6 

Networks B-2 

©note 

defined 5-5, 5-45 to 5-48 
example 5-10,5-39,5-42 
Note buffers 

adding 5-17 to 5-19 
adding text to 5-14,5-41 
copying contents to structured 
file 5-32 to 5-33 
initializing 5-59 to 5-60 
Note categories 5-5, 5-22 to 5-25 
Note commands, defined 5-3 
@note_file 

defined 5-5,5-48 to 5-49 
example 5-12 
Note files 5-5 

attaching to items 5-5,5-12, 5-43 
to 5-48 

creating external 5-43 to 5-45 
identifying with note tags B-8 to 
B-10 

naming 3-9 


Notes See also Category notes; Item 
notes 

adding to categories 3-7 to 3-4, 
5-22 to 5-25, B-8 to B-9 
adding to items 3-4,3-9 to 3-10, 
5-43 to 5-48, B-9 to B-10 
appending text to 5-5, 5-17 to 
5-19,7-11 to 7-12 
assigned to empty items 2-11 
converting with structured file 
tags B-2, B-8 to B-9 
copying to structured files 5-4, 
5-32 to 5-33,5-62 to 5-64 
debugging 7-4 to 7-5 
importing 3-10,6-6 to 6-7 
indicating with {N} tag B-3 
initializing memory buffers for 
5-32 to 5-33,5-59 to 5-60 
maximum number of characters 
in 5-46 

removing text from 5-56 to 5-59 
single 7-10 to 7-11 
stored in buffers 2-11 
tables converted to 3-10 to 3-16, 
5-62 to 5-64 
tagging 2-11 

text converted to 1-10 to 1-11, 
2-10 to 2-11,3-7 to 3-9,5-22 to 
5-27,5-43 to 5-49 
Note symbol (/) 1-14,3-10 
{N} note tag B-3 to B-4, B-8 to B-10 
Note tags B-8 to B-10 
Number sign (#) 2-5 
Number-vertical bar (# !) B-ll to 
B-12 

©numeric 5-4,5-49 to 5-50 
Numeric categories 5-62 

assigning numbers to 5-3, 5-26 
converting to 5-49 to 5-50,5-62 
example 3-14 

Numeric constant arguments 
defined 5-10 
example 5-39 

Numeric values 3-11 to 3-16,3-15, 
5-49 to 5-50 


O 

/O conversion option 6-2, 6-4 to 

6-5,7-3, A-2 

{O} note tag B-4, B-8 to B-10 
Optional arguments 5-7, 5-8,5-14, 
5-65 

Ordering definition file statements 
1-11 to 1-15,7-9 to 7-10 


P 

Paragraphs 1-2, 6-3 
Paragraph separators 6-5 
Parent categories See also Catego¬ 
ries; Category hierarchy 
adding child categories to 5-19 to 
5-22,5-25 to 5-27 
converting to 1-9 
indicating with category charac¬ 
ters B-12 
Parentheses 

in Agenda 2.0 A-3 
arguments in 5-8, D-6 
defined 4-11, C-2 
in ©end 5-32 
in nested levels D-6, D-7 
Pattern constant arguments, 
defined 5-10,5-22 
Patterns See Definition file 
patterns 

Percent sign (%) B-13 to B-14 
See also Escape character 
Period (.) 3-5,4-5,4-12, C-5 
{.} category tag B-4, B-10 to B-14 
Plus {+) 3-15,4-5,4-12 to 4-13,4-17, 
C-2 

Predefined variables 5-13, C-5 
Problems See Debugging; Error 
messages 

Processing files See Converting; 
TXT2STF 

Protecting structured files B-2 

R 

Ranges of characters 4-5 to 4-8,4-18 
to 4-19 
Removing 

spaces 5-15 to 5-16 
text from categories and items 
5-2, 5-56 to 5-59 
text and spaces with ©trim 5-1, 
5-10,5-21, 5-64 to 5-66 
text from text lines 3-6,5-5,5-60 
to 5-61 

©replace 5-5,5-51 

Replacing text 3-7,4-2,5-51 to 5-54 

Reports, converting 3-10 to 3-16 

Reserving memory 3-6 

©reset 5-6,5-52 

Running TXT2STF 6-1 to 6-2, A-l to 
A-2 

s 

Saving See also Storing 
categories with ©end 3-14 
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information in ASCII files 3-10 to 

3- 11 

text in variables 3-6 to 3-7,5-55 
{S} comment tag B-4, B-6 
/S conversion option 2-8, 6-2,6-5 
Searching for characters See Match¬ 
ing 

Selecting portions of text lines 7-10 
to 7-11 

Semicolon (;) B-5 to B-6 
Separator characters 2-3 to 2-4,5-34 
to 5-36,6-5 

©set 

defined 3-6,5-6, 5-55 
example 5-54,5-61 
Single quotation mark (') 4-2,5-7 
©skip 

defined 3-6,5-5,5-55 to 5-57 
example 5-2,5-26 to 5-27,5-39, 
5-42 

@skip_lines 

debugging 7-6 to 7-7 
defined 5-5,5-57 to 5-59 
example 5-10,5-23,5-62 to 5-64 
Skipping lines 5-57 to 5-59,7-11 to 
7-12 

Skipping over text 5-39, 5-55 to 
5-57,7-10 to 7-11 
Slash (/) 6-3, B-ll to B-12 
indicating exclusive category 
B-ll to B-12 
Spaces 

removing 5-15 to 5-16 
separating patterns from com¬ 
mands 2-3 to 2-4 
starting text lines with 3-5,4-2 
Special patterns 4-2 to 4-3, C-2 
Specific patterns See Definition file 
patterns 
Specifying 

assignments 6-7 
carriage returns 5-13 
categories with tags 2-11,7-4 to 
7-5, B-3, B-10 to B-14 
category types 5-10,5-20,5-62 
definition file patterns 7-8 to 7-9, 
C-l to C-2 

definition files 6-2 to 6-4,7-2 
file names with variables 5-12 
line feeds 5-13 

names for structured files 6-4,7-3 
ranges of characters 4-5 to 4-8, 

4- 18 to 4-19 

termination patterns 5-57 to 5-59 
values for variables 5-6, 5-52 
variables 5-12,5-33 to 5-34,5-52, 

5- 64 to 5-66 

Square brackets See Brackets ([ ]) 


Standard categories 5-4, 5-10,5-20, 
5-62, B-10 to B-12 
©start 

defined 3-6,5-4, 5-59 to 5-60 
example 5-15,5-23 
grouping statements with 7-14 
Start-of-line character See 
Caret ( A ) 

START pattern 4-2 to 4-3, C-2 
Statements See Definition file state¬ 
ments 

{STF} header tag A-6, B-4 to B-6 
Stopping See also Terminating 
conversion 5-22 
definition files 3-9 
TXT2STF 2-11 
Storing See also Saving 

converted information 2-5 to 2-7 
error messages in files 7-4 
patterns in variables 5-6 
text in memory buffers 2-11 
text in variables 3-6 to 3-7,5-6, 
5-11,5-52, 5-55 

values in variables 5-34 to 5-36 
String constant arguments 
defined 5-8 to 5-10 
example 5-14 
Strings See also Text 

appending to items 5-4,5-14 to 
5-16 

appending to notes 5-5, 5-17 to 
5-19 

appending to variables 5-6,5-13 
to 5-14 

as arguments 5-8 
deleting from text lines 5-5,5-60 
to 5-61 

grouping characters in 4-11 
matching non-pattern 4-13, 4-17 
to 4-18 

patterns compared with 4-16 to 

4- 18 

specifying for variables 5-5,5-33 
to 5-34, 5-52 

specifying in patterns 4-5 
©strip 5-5, 5-60 to 5-61 
Structured files 

in Agenda 2.0 A-l to A-2 
building with TXT2STF 2-10 to 
2-11 

contents of B-2 

copying information to 2-11,5-4, 

5- 19 to 5-22, 5-32 to 5-33, 5-62 
to 5-64 

creating B-3 
defined B-l to B-2 
defining category notes in 5-23 
documenting B-6 


examining 7-4 to 7-5 
formatting dates in 4-3,5-29 to 
5-31 

importing 3-10,6-6 to 6-7, 7-4 to 
7-5, A-6 
naming 6-4, 7-3 
on networks B-2 
samples B-5, B-16 to B-20 
testing 6-7 

text files converted to 6-2,5-62 to 
5-64, B-5 to B-16 
Structured file tags 
in Agenda 2.0 A-5 
Category tags 7-4 to 7-5, B-10 to 
B-14 

Comment tag B-6 
Date format B-6 
defined B-3 

header {STF} A-6, B-5 to B-6 
importing with 7-4 to 7-5 
inserting into converted text 2-11 
Item B-14 to B-16 
Note B-6 to B-8 
syntax B-2 

Symbols and special characters See 
list at beginning of index 
Syntax See Definition file com¬ 
mands, syntax 
Syntax errors 7-5 to 7-8 

T 

©table 

in Agenda 2.0 A-5 
defined 5-5,5-62 to 5-64 
@end with 5-32 
example 3-12,5-32 
Table commands, list of 5-3 
Tables, converting 3-10 to 3-16, 5-62 
to 5-64, B-19 to B-20 
Tabs 2-3 to 2-4 
Tags See Structured file tags 
/T debugging option 7-3,7-7 to 7-8 
Terminating 
conversion 5-22 
definition file commands 5-13, 
5-57 to 5-59 
definition files 3-9 
TXT2STF 2-11 
Testing See Debugging 
Text See also Strings 

adding to items 5-4,5-14 to 5-16 
adding to notes 5-5,5-17 to 5-19 
appending to elements 7-11 to 
7-12 

in arguments 5-8 
converting to categories 1-9 to 
1-10,5-19 to 5-22,5-25 to 5-27 
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converting to items 1-10 to 1-11, 

3- 6 to 3-8,3-9 to 3-10, 5-37 to 

5-43,5-54 

converting to notes 1-10 to 1-11, 

2- 10 to 2-11,3-7 to 3-9,5-22 to 
5-25 

copying to variables 1-9 to 1-10 
defining range of characters 4-5 
to 4-8, 4-18 to 4-19 
deleting 3-6,3-9,3-13,5-6,5-64 to 
5-66 

inserting tags in 2-11 
layout 7-11 to 7-12 
matching multiple occurrences 

4- 12 to 4-13,4-17 
matching non-pattern 4-13,4-17 

to 4-18 

matching single character 4-9 to 

4- 10,4-12 

matching patterns to 1-11 to 1-15, 

3- 7 to 3-8,4-1 to 4-2,4-16 to 

4- 18,7-6 to 7-7 

removing from categories 5-56 to 

5- 59 

removing from text lines 3-6, 

5- 60 to 5-61 

replacing 4-2,5-51 to 5-54 
searching 4-16 to 4-18 
skipping over 7-10 to 7-11 
specifying literal strings 4-5 
storing in variables 3-6 to 3-7, 

5- 6,5-11,5-52,5-55 
Text files 

in Agenda 2.0 A-l to A-2 
analyzing 1-5 to 1-7,2-2 
ASCII 1-1,3-10 to 3-11 
conversion options 6-2 to 6-5 
converting 1-11 to 1-15,2-7 to 

2-13,5-37 to 5-43,5-45 to 5-47, 

6- 1 to 6-3 

converting more than one 6-6 
end of 3-9,5-13,5-45, D-8 
invalid formats D-8 
moving to end of 3-9 
processing with TXT2STF 1-2 to 

1-3 

separator characters in 6-2 to 6-3, 

6-5 

types of information in 2-6,7-13 
to 7-14 

using definition files with 5-15 to 
5-16,5-21 to 5-22,6-3 to 6-4 
Text lines 

converting to items 1-10 to 1-11, 
5-37 to 5-39, 5-43 
copying to buffers 2-8 to 2-9, 5-37 
to 5-39 

copying to note files 5-43 to 5-45 


debugging format of 7-7 to 7-8 
deleting text from 5-5,5-60 to 
5-61, 5-64 to 5-66 
deleting values from 5-5, 5-55 to 
5-57 

discarding 5-57 to 5-59 
displaying 7-3, 7-7 to 7-8 
dividing into values 3-15,5-5, 
5-21, 5-34 to 5-36,5-55 to 5-57 
identifying for conversion 4-15 
length of 2-8, D-8 
matching 3-7 

matching beginning 4-8 to 4-9, 

4- 16 

matching end 4-11,4-16 
matching patterns to 1-11 to 1-15, 

2-8,3-7 to 3-8,4-1 to 4-2,4-16 
to 4-18 

processing with TXT2STF 2-8 to 

2- 9,3-7 to 3-8 

removing text from 3-6,5-5,5-60 
to 5-61, 5-64 to 5-66 
replacing 3-7,5-6,5-51 to 5-54 
selecting portions of 7-10 to 7-11 
skipping 5-5,5-57 to 5-59,7-11 to 

7-12 

spaces in 3-5,4-2 
storing in variables 5-5, 5-55 
Text values 5-67 to 5-68 
Tilde (~) 

in Agenda 2.0 A-3 
defined 4-5,4-13,4-17 to 4-18, 

7-9, C-2 

in patterns 7-9, D-6 
Times 5-3,5-4, 5-28 to 5-31, B-6 to 
B-8 
©trim 

in Agenda 2.0 A~5 
defined 3-6,5-5,5-6,5-64 to 5-66 
placing text in variables 5-27 
removing spaces with 5-15 to 

5- 16 

removing text with 5-2,5-10,5-21 
©skip compared with 5-56 
Trimming commands, defined 5-3 
Troubleshooting See Debugging 
TXT2STF 

ASCII files converted with 1-1, 

3- 10 to 3-11 

building structured files with 
2-10 to 2-11 

comparing patterns with strings 

4- 16 to 4-18 

controlling with definition file 
statements 2-3 

debugging options with 4-15 
defined 1-1 to 1-3 


definition files used by 2-7 to 
2-13 

error messages D-l to D-2 
executing definition file com¬ 
mands 3-6,5-2,7-10 
matching with 4-18 to 4-19 
memory problems with 2-4 
running 1-4,2-7 to 2-13,6-1 to 

6-2, A-l to A-2 

storing information with 2-5 to 

2- 7 

tables converted with 3-10 to 

3- 16, 5-62 to 5-64, B-19 to B-20 
terminating 2-11 

text lines converted with 2-8 to 
2-9,3-7 to 3-8 

TXT2STF command 6-2 to 6-3,7-2 
Type constant arguments 5-10 

u 

/U debugging option 7-3 
©unindexed 5-4, 5-67 to 5-68 
Unindexed categories 5-4,5-62,5-67 
to 5-68, B-ll to B-12 
Uppercase See Case 

V 

Values 3-15 

assigning to variables 5-34 to 

5-36 

category 2-11 
date 3-15, 5-28 to 5-29 
deleting from text lines 5-5,5-55 
to 5-57 

dividing text lines into 3-15,5-5, 
5-21,5-34 to 5-36,5-55 to 5-57 
numeric 3-11 to 3-16,5-49 to 5-50 
removing 5-64 to 5-66 
replacing text lines with 5-6 
specifying for variables 5-6,5-52 
storing in variables 5-34 to 5-36 
Variable argument 5-11 
Variable commands, defined 5-3, 

5-6 

Variable names 
defined 5-12 

equating with patterns 5-6,5-33 
to 5-34 
length of D-5 

Variable name string constant argu¬ 
ment 

defined 5-9, D-5 
example 5-14 
Variables 

in Agenda 2.0 A-4 to A-5 



appending strings to 5-6,5-13 to 
5-14 

as arguments 5-9, 5-11 
copying text to 1-9 to 1-10 
creating 5-3,5-13 to 5-14 
defined 5-11 
displaying 7-3, 7-8 
EOF 3-9,3-15,5-13,5-39,5-45, 
5-58 

errors specifying 7-8, D-4 
FILENAME 3-9,5-12,5-48 to 5-49 
initializing 5-3,5-32 to 5-34 
invalid D-5 
maximum size 5-11 
patterns assigned to 7-9 
patterns stored in 5-6 
predefined 5-13, C-5 
specifying 5-5, 5-12,5-33 to 5-34, 
5-52,5-64 to 5-66 
text stored in 3-6 to 3-7,5-6,5-52, 
5-55 

values assigned to 5-34 to 5-36 
values stored in 5-34 to 5-36 
/V debugging option 7-3,7-7 to 7-8 
Vertical bar ( i ) 

defined 4-5,4-13, C-2 
indicating unindexed category 
B-ll to B-12, D-6 


w 

{W} date tag B-4, B-12 to B-13 
When dates 

converting 1-8 to 1-9 
creating with tags B-12 to B-13 
variables for 5-13 
Worksheet, 1-2-3 3-11,5-62 
Writing 

comments 2-5 

definition file commands 1-7 to 
1-9 

definition file patterns 4-4,7-8 to 
7-9 

definition files 2-3 
definition file statements 1-7 to 
1-15,2-3 to 2-5 
W variable 5-13 



